MCP

接続方法

Chatty MCP の接続先は https://app.chatty.net/mcp です。JSON-RPC 2.0 を Streamable HTTP で送信します。ステートレスのため、各リクエストに認証情報が必要です。対応する HTTP メソッドは POST です。

API キーと App ID は Settings → General → Manage keys で確認します。キーはストアごとに最大 5 個です。キーはサーバーで保管し、ブラウザーや公開リポジトリに含めないでください。REST の X-Api-Key ヘッダーは MCP の認証には使えません。

add_note、update_tags、assign_member は、引数の convoId を省略すると X-Chatty-Convo-Id ヘッダーを使います。

curl -s -X POST "https://app.chatty.net/mcp" \
  -H "X-App-Id: $CHATTY_APP_ID" \
  -H "Authorization: Bearer $CHATTY_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

OAuth はクライアントの接続画面から開始し、ログインしてストアと権限を選びます。認可コードフローと PKCE S256 に対応しています。refresh token が必要なクライアントは offline_access を要求します。メタデータは同じホストの /.well-known/oauth-protected-resource/mcp と /.well-known/oauth-authorization-server で取得できます。

OAuth の scope

付与される scope は、メンバーの現在のロールと権限によって制限されます。knowledge:write と settings:write は admin が対象です。conversations:write は会話の edit 権限を持つ staff / member にも付与できます。helpdesk.helpcenter:read は Help center の閲覧権限を持つ staff / member にも付与できます。既存の接続に新しい scope は自動では追加されないため、付与するには再接続してください。OAuth は会話への返信などに対応しますが、Webhook 操作は提供しません。get_campaigns は campaigns:read があれば利用できます。

利用できる tool

tool 名は合計 144 個です。API-key server では最大 136 個（23 個の Helpdesk tool を含む）、OAuth server では最大 71 個を利用できます。両方に共通する tool もあります。

OAuth の 71 個の内訳は、既存の参照・ID 確認 tool 47 個、Public resource tool 16 個、proposal tool 8 個です。Public resource tool 16 個は、会話 tool 12 個（メンバーと顧客の会話の参照を含む）、get_shop_analytics、読み取り専用の manage_translations、manage_faq、manage_help_center です。チャネル、連携、翻訳、FAQ、Help center の書き込みは API key 専用で、OAuth クライアントは状況を参照し、connectUrl に案内します。

接続後は tools/list で現在の一覧と正確な入力 schema を取得してください。tool の登録は scope、ストア設定、連携状態で決まります。以下の — は登録時に scope を確認しないという意味で、認証不要という意味ではありません。

同じリソースの write scope は read も含みます。settings:write はすべての settings domain の write を含み、settings.widget:write などの domain write も settings:read を許可します。旧キーで管理 tool を使うには、必要な scope を付けたキーに切り替えてください。

Core tools

旧キーはこの 8 個を引き続き利用できます。OAuth で利用できるものは表の OAuth 列を確認してください。

send_message は text の前後の空白を除き、最大 5,000 文字です。ボットとメンバーのどちらの送信にも適用されます。

Storefront tools

API key 専用です。最後の列は必要な設定・連携条件です。Products、Collections、Discounts、Size guide は初期状態でオフ、Order tracking と After-sale support はオンです。Order tracking は Basic 以上、Size guide は Pro が必要です。human_agent_transfer は旧設定に関係なく常に登録されます。Joy (opens in a new tab) は API アクセスが可能なプランでの接続が必要です。

Products を有効にすると、商品検索とカートの読み書きがまとめて有効になります。カートだけのスイッチはありません。customer_support と human_agent_transfer はボット向けの応答を返します。顧客に表示するには send_message を呼びます。初回は確認を求め、顧客が実際に同意した後で isConfirmed: true を渡してください。

商品・注文・カートの入力例と詳細 schema は Tool Reference をご覧ください。注文番号による追跡では、番号に加えて顧客の email または phone が必要です。追跡番号による追跡には trackingNumber を渡します。

Admin tools

API key に明示的な scope が必要です。このうち OAuth でも登録されるのは get_setup_status だけです。OAuth でナレッジや設定を変更するときは、後述の proposal tools を使います。

update_settings の updates は Public API と同じ公開フィールドの検証を受けます。create_knowledge_entry の任意の status は active、draft、inactive です。

Merchant read tools

API key では明示的な scope が必要です。すべて読み取り専用です。get_webhook_subscriptions は読み取り操作でも conversations:write が必要です。OAuth の tool 登録対象からは明示的に除外されています。

chatty_whoami の tools は merchant catalog の一覧です。API key の Core・Storefront を含む実際の一覧には tools/list を使ってください。

入力と結果

• search_conversations の status は open、resolved、pending。dateFrom と dateTo は有効な YYYY-MM-DD です。limit は 1–50、既定値は 20。get_conversation も同じ limit と cursor を使います。get_conversation_trace は 1–20 ターンと、0 以上の afterTurnIdx を指定できます。
• get_ai_revenue、get_lost_opportunities、get_product_interest、get_answer_performance は日付またはオフセット付き ISO timestamp と、任意の IANA timeZone を受け付けます。集計期間は両端を含めて 1–90 日で、ストアの現地日付で直近 3 日は除外します。終了日が新しすぎる場合は調整され、window.clampedTo に記録されます。開始日を省略すると、有効な終了日を含む 30 日間が使われます。get_conversation_analytics は同じ期間制限で日付を指定します。AI が関与した売上は attribution であり、AI が売上を生んだという因果関係を示すものではありません。
• get_analytics_overview、get_ai_analytics、get_sales_analytics は from / to（YYYY-MM-DD）、または range を使います。値は today、yesterday、last-3-days、last-7-days、last-30-days、last-3-months、this-month、last-month。既定値は last-30-days です。
• query は string、number、boolean の値を持つ任意のフィルターです。get_scenario_support の linkable_training_data では query.type が必要です。値は url、shopify_page、file、qna、in-app、product、collection、discount。revision では scenarioId が必要です。get_settings_resource の feature には id、get_knowledge_operation の import_job にはジョブの id を指定します。
• get_channels と get_integrations は認証情報を返しません。requiresMerchantAction: true の接続では、マーチャントを connectUrl に案内してください。Channels and integrations をご覧ください。
• 顧客とキャンペーンの結果は必要な範囲に絞られ、REST の全フィールドは含まれません。Webhook の参照結果に署名用 secret は含まれず、failureCount24h、deactivatedReason、deactivatedAt が含まれます。Subscription tools は請求情報の参照のみで、プランは変更できません。

Core と Storefront は MCP の content に text を返します。多くは JSON ですが、No products found. のような通常のテキストを返す場合もあります。Merchant read tools は structuredContent も返し、配列は { "rows": [...] } に入ります。存在する場合は structuredContent を優先し、isError、error フィールド、text を確認してください。

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_conversation",
    "arguments": { "conversationId": "conv_123", "limit": 20 }
  }
}

リソースがない場合のエラー情報は { "error": "NOT_FOUND", "message": "Not found" } で、isError: true が付きます。表示用 text は tool によって異なります。

Public resource tools

以下の 44 tool は、REST と同じ処理を使う 180 操作を提供します。API キーでは明示的なスコープが必要で、旧キーと空のスコープ配列には登録されません。グループ内で 1 つでも許可された action があれば tool が一覧に表示されますが、呼び出し時に選んだ action のスコープを再確認します。一覧にあるだけで全 action が許可されるわけではありません。

OAuth では、以下で API key + OAuth と記載した tool だけを利用できます。manage_translations と manage_faq は OAuth では読み取り action のみ利用できます。会話の書き込みには、ログイン中のメンバーが現在 Inbox の会話を編集する権限を持っている必要があります。各書き込みの直前に再確認するため、権限を削除すると以前の token でも操作できません。

入力のルール: パスに使う ID は body の中ではなく action と同じ階層に置きます。省略とある行では action を送らず、tool 名で操作を指定します。未定義の最上位フィールドは拒否されます。body の ? は任意、string[] は文字列の配列、— は body 不要を意味します。表はフィールドの構造で、そのまま貼り付ける JSON ではありません。スコープを + で結んだ行は両方が必要です。

{"field.path": value} は、書き込み可能な設定パスと値を並べた平坦なオブジェクトです。たとえば similar_matching では {"similarMatchingSettings.forceSimilarByTags": false} を使います。パス、型、enum、必要なプランは get_settings_resource の resource: "fields" または Settings で確認できます。updates で包みません。変更しない任意フィールドは省略してください。

グループの tool で内部メモを追加する例です。

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "manage_conversation_notes",
    "arguments": {
      "action": "add",
      "conversationId": "conv_123",
      "body": { "text": "Follow up tomorrow" }
    }
  }
}

ask_ai

AI に質問し、会話を継続。

接続: API key + OAuth. 入力: message, conversationId, customer.

message（1–5,000 文字）、任意の conversationId と customer: {email?, phone?, name?} は body に入れず最上位に指定します。OAuth では customer を無視します。返された conversationId を次の質問に使います。

delete_conversation

会話と関連データを削除。

接続: API key. 入力: conversationId.

export_conversations

会話を最大 1,000 件、JSON または CSV でエクスポート。

接続: API key. 入力: body.

body はフィルターを含め POST /conversations/export と同じです。CSV は text の content として返り、_meta.mimeType が付きます。

export_customers

顧客データのエクスポートをストアのメールアドレスへ送信。

接続: API key. 入力: action, id, body.

{"queued":true,"recipient":"o***@example.com"} を返します。宛先は選べません。ストアごとに 1 時間 10 回の上限は REST と共有です。customers:write に customers:export は含まれません。

get_conversation_transcript

1 件の会話の、顧客に見えるメッセージを text または CSV で返す。

接続: API key. 入力: id, format.

format は txt（既定）または csv です。内部メモとアクティビティは含まれません。

get_member

ストアのメンバーを取得。

接続: API key + OAuth. 入力: memberId.

memberId と conversations:read を使い、既存の /chat/members/:memberId の処理を呼びます。別の tool である manage_members の get は、id と members:read を使い、GET /members/:id に対応します。

get_shop_analytics

顧客のインテント、満足度、キャンペーンのイベント、対応の指標、チャットから購入までのレポートを、現在のプランの制限に従って取得。

接続: API key + OAuth. 入力: action, from, to, range, id, phases, intents.

from と to（YYYY-MM-DD）、または range を使います。Analytics と同じで、期間は 1–90 日です。phases と intents は customer_intents 用のカンマ区切りフィルターです。結果は REST の body {success, data} です。ストアのプランに含まれないチャットから購入までのフィールドは、REST と同様に除外されます。

list_customer_conversations

顧客の会話をページ送りで取得。

接続: API key + OAuth. 入力: customerUuid, limit, cursor.

任意の limit は 1–100、cursor は前の結果からコピーします。

list_intents

有効な会話インテントのラベル一覧を取得。

接続: API key. 入力: なし。

manage_ai_clients

AI client の接続を一覧表示し、指定メンバーの接続を解除。

接続: API key のみ。OAuth: 利用不可。入力: action, body.

manage_api_keys

API キーを一覧表示・作成し、権限の変更や失効を行う。

接続: API key のみ。OAuth: 利用不可。入力: action, id, body.

manage_campaigns

キャンペーンを作成・更新・削除・公開・並べ替えし、現在のプランで不足している既定のキャンペーンを作成。

接続: API key. 入力: action, id, body.

defaults は現在のプランで不足している既定のキャンペーンを作成し、その ids を返します。作成される Welcome message キャンペーンはすぐに有効になります。Campaigns をご覧ください。

manage_conversation_attributes

会話の属性を作成・更新・削除。

接続: API key + OAuth. 入力: action, attributeId, conversationId, body.

manage_conversation_notes

会話のメモを追加・更新・削除。

接続: API key + OAuth. 入力: action, conversationId, noteId, body.

manage_conversation_tags

会話から 1 個のタグを削除。

接続: API key. 入力: conversationId, tag, body.

manage_customer_memory

顧客の記憶情報を追加・更新・削除・再生成。

接続: API key. 入力: action, id, factId, conversationId, body.

manage_customer_tags

顧客タグを一覧表示・追加。

接続: API key. 入力: action, body.

manage_customers

顧客を作成・更新・削除。

接続: API key. 入力: action, id, body.

manage_faq

エクスポートや削除の進捗の参照、FAQ 行のインポート、すべての FAQ の削除、カテゴリー・質問・ブロックの管理、ナレッジへの同期。

接続: API key + OAuth（OAuth は export と delete_all_progress のみで、knowledge:read が必要）. 入力: action, id, status, format, overwrite, publish, body.

status（all または published）と format（csv または json）は export に、overwrite と publish は import に使います。delete_all はバックグラウンドですべての FAQ を削除するため、delete_all_progress で進捗を確認してください。Import, export, and delete all FAQs をご覧ください。

manage_help_center

Help center の設定とレポートを取得し、Help center の書き込み scope があれば設定、ストアページ、色、アセットを更新。

接続: API key + OAuth（OAuth は読み取り action のみで、helpdesk.helpcenter:read が必要）. 入力: action, kind, periodDays, body.

periodDays は 7、30、90 です。kind は logo、whiteLogo、favicon です。update_settings は revision が古い場合に STALE_SETTINGS を返すため、読み直して再試行してください。upload_asset は url を返すので、update_settings で保存します。Helpdesk がないストアでは HELPDESK_DISABLED が返ります。上限とエラーは Help center をご覧ください。

manage_integrations

資格情報を使うサポート対象の連携の接続、チャネル設定の変更、チャネルと連携の接続解除。マーチャントのログインが必要な接続には connectUrl を使います。

接続: API key. 入力: action, app, id, pageId, phoneId, body.

app と、各プロバイダーが受け付ける資格情報は Supported providers に掲載しています。未対応の操作は INVALID_PARAMS を返します。disconnect_facebook はすべてのページと、それらにリンクされた Instagram アカウントを削除します。書き込みの結果は {success, data} の body 全体を保持します。資格情報は結果と MCP call audit から除かれます。

manage_knowledge_entries

ナレッジの作成・更新・削除・インポートと学習管理。

接続: API key. 入力: action, id, body.

manage_knowledge_suggestions

ナレッジへの提案を生成・承認・スキップ。

接続: API key. 入力: action, id, decision, body.

bulk_decide では最上位の decision に accept または skip を指定します。

manage_languages

言語を追加・更新・削除し、既定の言語を設定。

接続: API key. 入力: action, code, body.

manage_market_overrides

マーケット別の設定を保存・削除。

接続: API key. 入力: action, marketId, body.

manage_members

メンバーと通知設定を取得し、スタッフを招待・管理。

接続: API key のみ。OAuth: 利用不可。入力: action, id, body.

manage_product_faqs

商品 FAQ を保存・削除。

接続: API key. 入力: action, id, productId, body.

manage_recommendations

商品レコメンド、組み込みのメタタグ、Shopify のレコメンド設定を参照・管理。

接続: API key. 入力: action, id, metaTag, limit, sort, after, before, hasCount, body.

metaTag は best_selling または newest です。limit、sort、after、before、hasCount は list に使います。Product recommendations をご覧ください。

manage_scenarios

シナリオと保留中の変更を管理。

接続: API key. 入力: action, id, body.

manage_shop_memory

ストアの記憶情報を学習・削除。

接続: API key. 入力: action, id, body.

manage_shortcuts

ショートカットとカテゴリーを作成・更新・削除。

接続: API key. 入力: action, id, body.

manage_size_guides

サイズガイドを作成・更新・削除。

接続: API key. 入力: action, id, body.

manage_translations

言語ごとの翻訳済みコンテンツを参照・編集、またはリセット。

接続: API key + OAuth（OAuth は get のみで、settings:read が必要）. 入力: action, code, id, body.

編集できるパスとプランの条件は Languages and translations をご覧ください。リセットは、ストアごとに 1 時間 5 回の上限を REST と共有します。

manage_unresolved_questions

未解決の質問を解決・削除。

接続: API key. 入力: action, id, body.

manage_webhooks

購読の管理、配信と失敗の確認、保持されている配信の再送、テスト ping の送信。署名用 secret は一度だけ返されます。テスト ping は、ストアごとに 1 時間 10 回の上限を REST と共有します。

接続: API key. 入力: action, id, deliveryId, status, cursor, body.

status（HTTP status、または 0）と cursor は list_deliveries の絞り込みとページ送りに使います。保持期間と上限は Monitor deliveries をご覧ください。

mark_conversation_read

チーム側で会話を既読にする。

接続: API key + OAuth. 入力: conversationId, body.

set_conversation_state

会話を解決済みにする、または再開する。

接続: API key + OAuth. 入力: conversationId, body.

set_conversation_typing

担当者の入力中表示を設定。

接続: API key. 入力: conversationId, body.

set_feature

機能を有効化・無効化。

接続: API key. 入力: action, key, body.

start_conversation

メールで新しい会話を開始。

接続: API key + OAuth. 入力: body.

trigger_sync

学習リソースの同期を開始。

接続: API key. 入力: resource, body.

resource は products、discounts、pages です。

update_settings_resource

設定コレクションを更新。

接続: API key. 入力: action, body.

update_shop_preferences

ストア全体のメールとウィジェットの設定を更新。

接続: API key. 入力: action, body.

少なくとも 1 つのフィールドを送ってください。現在の値は get_settings_resource（resource: "shop_preferences"）で確認できます。

update_training_status

商品・ディスカウント・コレクションの学習状態を変更。

接続: API key. 入力: action, body.

メンバーとキーの管理

この 3 つの管理 tool は API キー専用です。OAuth のメンバーが admin でも利用できません。manage_members の参照には members:read、変更には members:write が必要です。manage_api_keys は一覧も含めて api_keys:write、manage_ai_clients は読み取り専用の一覧にも members:write が必要です。

メンバーへの書き込みと、API キー・AI client のすべての管理操作では、キー作成者が現在も同じストアの有効な adminである必要があります。呼び出しごとにメンバーを読み直すため、scope だけでは操作できません。作成者情報がない、作成者が削除・無効化されている、admin でなくなっている場合は KEY_OWNER_NOT_ADMIN になります。キーの ID、作成者、scope は認証から決まり、body では指定できません。

メンバーの入力と変更の影響

• invite は有効な email が必須で、firstName、lastName、permissions は任意です。スタッフへの招待メールを送り、プラン・追加席数・メンバー数の上限を確認します。REST と MCP で共有する上限はストアごとに 20 招待/時間です。
• MemberUpdate は、文字列の firstName、lastName、fullName、storeAlias、boolean の enabledAIResolvedReport、enabledChatPerformanceReport、enableAwayMode、unresolvedReportRecipients、performanceReportRecipients、permissions オブジェクトを受け付けます。各宛先フィールドは有効なメールアドレスを最大 10 個、文字列配列またはカンマ区切り文字列で指定できます。email、role、avatarUrl、有効・無効の状態はこの action では変更できません。有効・無効は status と body.active で変更します。省略したフィールドは維持され、変更可能な項目がない更新は拒否されます。
• permissions は権限キーと許可レベルの対応です。例は {"inbox.conversations":"view"}。キーはメンバー権限 catalog に存在し、指定レベルに対応している必要があります。レベルはキーによって none、view、edit です。admin の権限は変更できません。API キーの scope とは別の設定です。
• update、status、delete で admin を対象にすると ADMIN_TARGET_FORBIDDEN になります。スタッフの有効化では席数を確認します。無効化は OAuth 接続と Firebase refresh session を失効させ、push 購読を解除します。削除は session の失効後にメンバーを削除し、未解決の会話の再割り当てを試みます。再割り当てに失敗してもメンバーの削除は取り消されません。有効なメンバーへの招待再送は ALREADY_ACTIVE になります。
• update_notifications は表にある 5 項目だけを受け付け、verifiedTopicEmail と push token は書き込めません。enabledSoundOpt は all、first、none。forwardTopicEmails は最大 10 個の有効なメールアドレスです。未認証の新しい topicEmail はメール認証を開始しますが、それだけで認証済みにはならず、以前の認証済み配信先をすぐに置き換えません。無効なメンバーの pushTopics を変更すると MEMBER_INACTIVE になります。通知の更新は REST/MCP 共通で API キーごとに 30 回/時間です。
• pushTopics と emailTopics の対応値は conversation-assigned、new-message-assigned、conversation-mentioned、conversation-assigned-others、new-message-assigned-others、conversation-assigned-chatbot、new-message-unassigned、new-unassigned-from-ai、agent-unassigned、no-replies です。対応していない topic は除外されます。

メンバーの参照は公開プロフィールまたは保存済みの通知設定を structuredContent で返します。招待は {"success":true,"id":"member_123"}、ほかの書き込みは {"success":true} を返します。通知の参照結果には、読み取り専用の verifiedTopicEmail が含まれる場合があります。

API キーへの権限の委譲

API キー管理では操作のたびに Pro または Plus を確認し、有効なキーはストアごとに最大 5 個です。作成は REST と共通でストアごとに 10 回/時間。title は空白以外の内容が必要で最大 50 文字です。作成の scopes は任意で既定値は []、更新では必須となり、scope 一覧全体を置き換えます。

要求する各 scope は、呼び出し元キーが許可する範囲内である必要があります。write に含まれる read も考慮されます。api_keys:write はこの tool では委譲できません。admin が Manage keys で付与します。作成したキーの所有者は呼び出し元と同じです。更新・失効の対象は、同じストアの有効なキーで、明示された scope 全体が呼び出し元の許可範囲内である必要があります。旧キーはダッシュボードで管理してください。呼び出し元キー自身の更新・失効は CANNOT_REVOKE_SELF になります。別のキーを scopes: [] に更新すると、そのキーは失効します。

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "manage_api_keys",
    "arguments": {
      "action": "create",
      "body": { "title": "Inbox reader", "scopes": ["conversations:read"] }
    }
  }
}

この例には api_keys:write と、conversations:read を許可する権限の両方が必要です。作成結果の新しい secret は一度だけ返されるため、安全に保存してください。一覧は有効なキーの情報を rows に返し、id、maskedKey、title、scopes、apiVersion、保存済みの createdAt を含みます。secret やそのハッシュは含みません。更新・削除の結果は {"success":true,"id":"key_123"} です。

AI client の接続解除

manage_ai_clients の list は serverUrl と connections を返し、client とメンバーの組み合わせでまとめます。各接続の clientId と connectedByMemberId を、disconnect の body.clientId と body.memberId にコピーします。入力フィールド名に connectedByMemberId を使わないでください。認証されたストア内で、その client/メンバーに一致する有効な許可をすべて失効させ、{"success":true} を返します。失効した許可の件数は返しません。

これらの操作は共通 controller の検証と認証済み実行者の mutation audit を使います。処理から返るエラーには INVALID_PARAMS、NOT_FOUND、KEY_OWNER_NOT_ADMIN、ADMIN_TARGET_FORBIDDEN、PLAN_REQUIRED、MEMBER_LIMIT_EXCEEDED、ALREADY_ACTIVE、MEMBER_INACTIVE、CANNOT_REVOKE_SELF、FORBIDDEN、RATE_LIMITED があります。MCP のエラー結果とメッセージを確認してください。controller の REST status がそのまま MCP の HTTP status になるとは限らず、拒否された書き込みは成功ではありません。

チャネル、モニタリング、エクスポート、コンテンツ

API key の接続では、これまで管理画面が必要だった次の作業も実行できます。

• manage_integrations は、チャネルの設定変更、メールチャネルの追加、資格情報を使う連携の接続、チャネルと連携の接続解除を行います。settings.integrations:write が必要です。マーチャントのログインが必要な接続は、get_channels と get_integrations に requiresMerchantAction と connectUrl が表示されます。
• manage_webhooks は、配信の試行と失敗を一覧表示し、保持されている配信を再送し、テストイベントを送ります。
• get_shop_analytics は、インテント、満足度、キャンペーン、対応、チャットから購入までのレポートを、ストアのプランの制限に従って取得します。
• export_conversations と get_conversation_transcript は会話データを直接返します。export_customers は顧客データをストアのメールアドレスへ送信し、customers:export が必要です。
• manage_translations、manage_faq（インポート、エクスポート、すべて削除）、manage_recommendations、update_shop_preferences はコンテンツと設定を扱います。manage_help_center は Help center を読み取り、helpdesk.helpcenter:write があれば設定、ストアページ、色、アセットを変更します。

各 tool は、対応する REST ルートと同じルール、上限、audit 記録を使います。リンクは Tool Reference をご覧ください。

Body の詳細と削除操作

• ナレッジの Entry は既定で Q&A となり、question と answer が必要です。status は active、draft、inactive。bulk_create は entries 配列、一括 status 更新と削除は 1–100 個の ID を受け付けます。インポートには空でない text、content、entries、fileIds のいずれかが必要で、format は csv または json です。重複の解決には candidateId、entry と、create、merge、replace のいずれかの decision が必要です。ジョブが queued でも取り込みは完了していません。get_knowledge_operation で状況を確認します。
• FAQ カテゴリーのタイトルは name ではなく question に入れます。FAQ block はフィールドのオブジェクトを受け付け、faqs の各要素は questionId / categoryId で既存の質問・カテゴリーを指定します。更新前に get_faq_data で現在の block を読み、置き換えるフィールドを送ってください。シナリオ作成には name と instruction が必要で、対応する enum はフィールド情報で確認できます。サイズガイド作成には読み取れる Markdown のサイズ表と、ガイドを管理できるプランが必要です。
• キャンペーン作成では inactive の下書きができます。create/update で status: "active" を送らず、body.confirm: true を付けて publish を呼びます。condition、trigger、message、appearance はキャンペーンのネストしたオブジェクトです。更新前に get_campaigns で既存の設定を確認してください。任意のコンテンツ項目には contentMessageType、quickQuestions、viewSimilarButton、askAboutItButton、viewProductButton、shopNowButton、subscribeButton、skipButton、headerText、itemsInCartText、viewCartButton、completeOrderButton もあります。
• 顧客作成には email または phone が必要です。作成時は firstName / lastName、更新時は name を使います。CUSTOMER_EXISTS の existingId が返ったら、再作成せずその顧客を更新してください。fact は 1–500 文字。factType は preference、size、behavior、demographic、issue、contact です。追加時は既定で behavior、更新時は必須です。要約の再生成は API キーごとに 10 回/時間です。
• manage_customers の delete には customers:write と conversations:delete の両方が必要で、顧客に紐づく会話も削除します。delete_conversation は conversations:delete が必要です。未計上の AI 使用量を計上する場合があり、最後の会話を削除すると顧客も削除されます。conversations:write に削除権限は含まれません。OAuth はどちらの削除 tool も利用できません。
• start_conversation はメールの会話を開始します。body.email と有効なストアメンバーが必要です。API キーでは body.memberId を指定するかキー作成者を使い、OAuth では常に接続中のメンバーを使います。subject は改行なしの最大 998 文字、message は 1–5,000 文字、participants は最大 5 個のメールアドレスです。message と files がない場合は初回返信を送らず会話だけを作成します。WhatsApp template の新規会話は開始できません。
• File は {filename: string, mimeType: string, data: string} で、data は base64 です。send_message.files と start_conversation.body.files は最大 10 件、デコード後は 1 件につき最大 5 MiB です。filename は最大 255 文字、MIME type は最大 200 文字。アップロードはストアごとに 60 バッチ/時間、会話の開始も別の枠で 60 回/時間です。ファイルをアップロードしてから送信します。開始時の UPLOAD_FAILED / SEND_FAILED に作成済みの conversationId が含まれる場合は、新しい会話を作り直す前にその会話を確認してください。

MCP は base64 を JSON で送信し、REST の multipart upload とは別です。Chat Conversations API の multipart は最大 10 件、1 件 20 MiB、合計 25 MiB ですが、MCP の 1 件 5 MiB という上限は変わりません。

既存 tool の入力との違い

OAuth の平坦な会話 tool では convoId を明示してください。API キー用の会話コンテキストヘッダーは使われません。ask_ai はストアの AI と返信枠を使い、用意したテキストを送る send_message とは異なります。会話の継続と使用量エラーは AI ask をご覧ください。OAuth の ask_ai は customer を除外します。

list_conversations のフィルター

実際の顧客の会話を取得し、REST の会話一覧と cursor ページ情報を structuredContent で返します。AI playground のテスト会話ではありません。OAuth は別の schema を持つ search_conversations を使い、そちらの limit は最大 50 です。

send_message の text は前後の空白を除き、ボットかメンバーか、API key か OAuth かを問わず、すべての送信で最大 5,000 文字です。超えると INVALID_PARAMS になります。topic はボット送信時の分類に使い、既定値は General inquiry。結果は { "messageId": "...", "convoId": "...", "saved": true } です。既存の Messenger、Instagram、WhatsApp、email の会話への返信は共通の配信ルールに従い、プラットフォームの送信可能時間の制限も適用されます。update_tags に以前の先頭 100 個という制限はなく、空の一覧では全削除できません。

assign_member のメールアドレス検索でメンバーが見つからない場合は、NOT_FOUND と Member not found を返します。メンバー ID が無効、非アクティブ、または別のストアに属する場合は、INVALID_PARAMS と memberId must be an active member of this shop を返します。

結果と監査

Public resource tools は認証済みストアと実行者の情報を使い、REST と同じ controller を呼びます。書き込みの mutation audit に実行者が渡り、MCP call audit には tool、結果、所要時間が記録されます。引数に shopId、実行者 ID、audit session を指定しないでください。これらは認証から決まります。

結果は structuredContent と表示用 text で返されます。REST の body が data だけならその中身を返し、他の envelope は維持します。配列は rows に入ります。HTTP 200 だけで成功と判断せず、error、success: false、isError を確認してください。OAuth の scope 不足は処理前の HTTP 403、または insufficient_scope などの tool error になる場合があります。必須のパス ID がない場合は INVALID_PARAMS。body の不正、リソース不在、使用枠、操作固有の失敗は controller の検証に従い、MCP で TOOL_ERROR として返される場合もあります。保留中のジョブ・提案や部分的な失敗は、書き込み完了ではありません。

OAuth proposal tools

以下の 8 個は OAuth 専用です。提案の作成は確認待ちレコードを書き込みますが、その変更をまだ適用しません。適用・却下には admin、対象の scope、人による確認が必要です。一方の write scope だけで、もう一方の領域の提案は承認できません。

action は create または update。設定以外の更新には targetId が必要です。payload は未定義のキーを受け付けません。

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "propose_custom_answer",
    "arguments": {
      "action": "create",
      "reason": "Answer a repeated delivery question",
      "payload": { "question": "Where can I track my order?", "answer": "Use the tracking link in your shipping email." }
    }
  }
}

クライアントの確認 UI で提案を確認してください。apply_proposal と reject_proposal は app 向けに公開され、人の操作が必要です。AI が確認 token を作って自分の提案を承認することはできません。エラーには INVALID_PAYLOAD、INSUFFICIENT_SCOPE、ADMIN_REQUIRED、NOT_FOUND、INVALID_STATE、CONFIRMATION_REQUIRED があります。

Helpdesk tools

以下の 23 個は、対応する Helpdesk scope を持つ API key で、API-key server から利用できます。ストアの Helpdesk のチケット、連絡先、Help center を操作します。OAuth には登録されません。操作は、呼び出したキーを実行者として記録されます。

Helpdesk の write scope は、すべての Helpdesk の read scope も満たします。sendType が send 以外の reply_to_ticket には helpdesk.tickets:write も必要です。forward_ticket は、ストアの転送許可リストにあるアドレスにのみ送信します。propose_order_action は、Helpdesk で担当者が承認するための提案をキューに入れるだけで、注文は変更しません。list_my_pending_actions は、このキーの提案だけを一覧表示します。Help center の propose_create_article、propose_update_article、propose_create_category、propose_update_category は、記事とカテゴリーについて同様に提案をキューに入れます。提案は Helpdesk で担当者が承認、却下、または元に戻すまで待機し、それまで何も変わりません。削除は提案できません。提案後に Help center が変更されていた場合、承認すると 409 と HELP_CENTER_PROPOSAL_STALE が返ります。list_my_pending_helpcenter_proposals は、このキーの保留中の提案だけを一覧表示します。

結果は JSON を含む text の content で返ります。失敗時は isError: true と {"code","message"} の body が付き、たとえば scope 不足では SCOPE_DENIED が返ります。helpdesk.skills:read、helpdesk.subscriptions:read、helpdesk.subscriptions:write に対応する Chatty MCP tool はまだありません。Help center の書き込みは、helpdesk.helpcenter:write を持つ manage_help_center で行います。

Webhook で受信して返信する

1. register_webhook（scoped key では conversations:write が必要）で message.created を購読します。
2. 署名を検証し、senderType: "customer" のイベントだけ処理します。ボット自身のメッセージに反応すると返信がループします。
3. 必要な情報を tool で取得し、send_message に convoId と text を渡します。

購読できるイベントは message.created、message.updated、message.removed、conversation.created、conversation.updated、conversation.state_changed、conversation.assigned、conversation.tags_updated、conversation.removed、customer.created、customer.updated です。customer.updated は顧客プロフィールの更新時に、conversation.updated は会話で検出されたメールアドレスまたは電話番号が変わったときに発生します。

新しい URL の登録時だけ、whsec_ と 48 桁の 16 進数からなる署名用 secret が返されます。同じ URL の再登録・一覧取得・更新では返されません。紛失した場合は Public API の Base URL に対して POST /webhooks/:id/rotate-secret を呼んでください。新しい secret が一度だけ返され、古いものは無効になります。呼び出し側で指定した secret は使われません。登録上限は 10 件です。Webhooks に検証方法を掲載しています。

ID は結果や Webhook からそのままコピーします。update_tags はタグ全体の置換なので、追加するときも先に既存の一覧を読みます。scope はストア全体に適用され、1 会話だけに制限することはできません。

Rate limits とエラー

このほか、Webhook のテストはストアごとに 10 回/時間、再送は購読ごとに 30 回/時間、顧客のエクスポートはストアごとに 10 回/時間、翻訳のリセットはストアごとに 5 回/時間、資格情報の検証はキーごとに 10 回/時間の上限があります。いずれも REST と同じ枠を共有します。

上限超過は HTTP 429 です。X-RateLimit-Limit と X-RateLimit-Remaining を確認し、時間を置いて再試行してください。REST は別の上限を使います。

API key の認証失敗は HTTP 401 と通常の JSON error を返します。X-App-Id がなく有効な OAuth token もない場合は invalid_token、OAuth の scope 不足は HTTP 403 と insufficient_scope、必要な scope を示す WWW-Authenticate を返します。認証済みで POST 以外を使うと 405 です。

登録されていない tool の呼び出しは MCP のエラーになります。tool 内部の失敗は HTTP 200 の結果に含まれる場合があるため、HTTP status だけで成功と判断しないでください。structuredContent、isError、text の error を確認します。

API key は各リクエストで確認されます。漏えいした場合は Settings → General → Manage keys で無効化し、新しいキーに切り替えて Webhook 登録も点検してください。tool error や確認待ち proposal を完了として記録しないでください。

接続設定例と Storefront tool の詳細は MCP overview と Tool Reference をご覧ください。