Help center

すべてのパスは Public API base URL を使います。各リクエストに X-Api-Key を付けてください。読み取りはボディなしの GET で、200 を返します。

helpdesk.helpcenter:write でできること

同じスコープでも、使う場所によって動作が異なります。

• この Public API と Chatty MCP では、 Help center を直接変更します。対象は設定、ストアページ、ストアの色、ブランドアセットです。変更はすぐに保存され、呼び出したキーとともに監査ログに記録されます。
• Helpdesk agent API と Helpdesk MCP tool では、 エージェントが記事とカテゴリーの作成・更新（削除は提案できません）を、Helpdesk tools の propose_create_article、propose_update_article、propose_create_category、propose_update_category で提案できます。各提案は Helpdesk で担当者が承認または却下し、元に戻すこともできます。それまでは何も変わりません。REST では、エージェントは X-Api-Key を付けて POST https://app.chatty.net/hd/v1/agent/help-center/proposals に同じ提案を送り、同じパスへの GET で自分の提案を一覧できます。

他の Helpdesk 書き込みスコープと同様に、すべての Helpdesk 読み取りスコープも付与されます。OAuth 接続では Help center を読み取ることしかできません。

Settings

GET /help-center/settings は、保存されている設定をデフォルト値に重ねて返します。一度も変更していないストアではデフォルト値が返ります。

{
  "data": {
    "settings": {
      "branding": {"title": "Help Center", "colorPreset": "store", "colorTheme": "light", "categoryLayout": "accordion"},
      "customDomain": {"status": "unverified"},
      "storePage": {"enabled": false, "handle": "helpcenter", "shopifyPageId": null},
      "seo": {"metaTitle": "Help Center", "enableIndexing": true, "generateSitemap": true},
      "contactMethods": {"liveChat": {"enabled": true, "label": "Chat with us"}, "email": {"enabled": false}},
      "contactForm": {"enabled": false, "customFields": []},
      "language": {"code": "en", "direction": "ltr"},
      "revision": 0
    }
  }
}

この例は抜粋です。customDomain.status は unverified、checking、active、failed のいずれかです。保存された設定には、customCss、customDomain.domain、seo.ogImageUrl も含まれることがあります。ドメイン認証用の DNS レコードは、このレスポンスには含まれません。

Overview

{
  "data": {
    "articles": {"draft": 3, "published": 24, "internal": 2},
    "categories": {"empty": 1, "total": 6},
    "previewArticleSlug": "track-my-order",
    "previewUrl": "https://help.example.com/hc/shop_123?preview=1",
    "storePage": {"enabled": true, "handle": "helpcenter", "hasShopifyStore": true, "shopifyPageId": "gid://shopify/Page/123", "url": "https://shop.myshopify.com/pages/helpcenter"}
  }
}

• articles.published は、お客様に表示される公開済みの一般向け記事の数です。internal は、公開済みで一般向けではない記事の数です。
• categories.empty は、記事が 1 件もないカテゴリーの数です。
• previewArticleSlug は公開済みの一般向け記事の 1 つで、ない場合は null です。previewUrl も null になることがあります。
• storePage.url は、ストアページが有効な場合のみ値が入り、それ以外は null です。

Search analytics

periodDays は必須で、7、30、90 のいずれかを指定します。期間は現在時刻までで、UTC で数えます。

curl 'https://app.chatty.net/v1/help-center/search-analytics?periodDays=30' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

{
  "data": {
    "total": 412,
    "zeroResult": 37,
    "topQueries": [{"query": "refund", "count": 58, "resultsCount": 4, "lastSearchedAt": "2026-10-22T09:12:00.000Z"}],
    "byDay": [{"date": "2026-10-21", "count": 19}],
    "zeroResultQueries": [{"query": "warranty", "count": 9, "lastSearchedAt": "2026-10-22T07:40:00.000Z"}]
  }
}

topQueries と zeroResultQueries はそれぞれ最大 50 件で、検索回数の多い順に並びます。resultsCount は、そのクエリで確認された結果数の最大値です。byDay は日付順です。結果が 0 件だったクエリは、次に書くべき記事の候補として役立ちます。

Change settings

PATCH /help-center/settings は、最後に読み取った revision と、変更したい設定を受け取ります。設定の形は GET レスポンスの settings と同じです。省略したフィールドは値が変わりません。

curl -X PATCH 'https://app.chatty.net/v1/help-center/settings' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"revision":3,"branding":{"title":"Support","primaryColor":"#1A1A1A"},"seo":{"metaTitle":"Support"}}'

{"success":true,"revision":4}

• リビジョンロック。 読み取りの後に他の誰かが保存すると、revision が一致しなくなり、ルートは 409 STALE_SETTINGS を返します。設定を読み直して変更をやり直し、新しい revision で再試行してください。保存に成功するたびに 1 増えます。
• 指定できるトップレベルのフィールドは branding、contactMethods、contactForm、contactPage、customDomain、language、seo、customCss です。それ以外のフィールドは 400 VALIDATION_FAILED になります。ストアページは下記の専用ルートを使います。
• 色は #1A1A1A のような 16 進数で指定します。テキストフィールドには文字数の上限があり、たとえば seo.metaTitle は 70 文字までです。contactPage の地図には住所が必要です。
• customCss(最大 51,200 文字)には Plus プランが必要で、Plus 未満では 403 CUSTOM_CSS_REQUIRES_PLUS を返します。保存済みの値をそのまま送り返す場合は、どのプランでも使えます。

Store page

PUT /help-center/store-page は {"enabled":true,"handle":"help"} を受け取ります。handle は省略可能で、小文字の英字、数字、ハイフンを使い、255 文字までです。省略した場合は、現在のハンドルまたは helpcenter が使われます。

• enabled: true は、Help center を表示するページを Shopify ストア上に作成または更新し、ハンドルが変わるとページを移動します。初回は、ストアの色も読み取ります。
• enabled: false は、そのページをストアから削除します。
• レスポンスは {"success":true} です。ページの URL は GET /help-center/overview で確認してください。

他のページがすでに使っているハンドルは 409 STORE_PAGE_HANDLE_TAKEN を返します。Shopify に接続していないストアは 400 STORE_PAGE_SHOPIFY_UNAVAILABLE を返します。Shopify 側の失敗は 502 を返します。

Store colors

POST /help-center/store-colors/sync はボディを取りません。ストアの現在のテーマの色を読み取り、store カラープリセットが使う branding.storeColors に保存します。{"success":true} を返し、revision は変わらないため、先に読み取った設定の下書きもそのまま保存できます。色を読み取れないテーマは status: "unreadable" で保存されます。Shopify に接続していないストアは 400 STORE_COLORS_SHOPIFY_UNAVAILABLE を返します。

Brand assets

POST /help-center/assets/{kind} は画像を 1 枚アップロードします。kind は logo、whiteLogo、favicon のいずれかです。

ファイルをちょうど 1 つ含む multipart、または mimeType、dataBase64、任意の name を含む JSON のどちらかで送ります。

curl -X POST 'https://app.chatty.net/v1/help-center/assets/logo' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -F '[email protected]'

{"data":{"url":"https://cdn.example.com/help-center/shop_123/logo/logo.png"}}

成功時は 201 です。ファイルの内容は種類と一致している必要があり、スクリプトを含む SVG ファイルは 400 INVALID_FILE で拒否されます。アップロードだけでは、まだ Help center は変わりません。返された url を PATCH /help-center/settings で保存してください(たとえば branding.logoUrl や branding.faviconUrl)。ストレージの失敗は 502 STORAGE_UPLOAD_FAILED を返します。

ルートのハンドラーまで届いた書き込みは、成功・失敗にかかわらず、呼び出したキーとともに監査ログに記録されます。スコープ不足や無効なキーで手前で拒否されたリクエストは記録されません。書き込みは冪等ではないため、結果が不明なリクエストを繰り返す前に設定を読み取ってください。

エラー

MCP では、manage_help_center が API キーまたは OAuth で同じリソースを読み取り、書き込みは API キーのみで行います。公開済みの記事を検索するには、API キー用のツール search_help_center と get_help_center_search_terms を使います。MCP ツールリファレンスを参照してください。