チャネルと連携

すべてのパスは Public API base URL を使います。各リクエストに X-Api-Key を付け、表で JSON ボディを指定している場合は Content-Type: application/json も付けてください。これらのルートは /chat では使えません。

共通のルール

• 書き込みのボディは厳密に検証されます。不明なフィールド、型の誤り、必須フィールドの欠落は 400 VALIDATION_FAILED を返します。ボディのないルートは、ボディなしまたは {} を受け付けます。
• 書き込みが成功すると {"success":true,"data":...} を返します。返す内容がない場合は {"success":true} です。
• レスポンスに認証情報は含まれません。トークン、API キー、webhook URL、ペアリングコード、シークレットは、どの階層にあっても送信前に取り除かれます。
• 別のストアの ID は、不明な ID と同じく 404 NOT_FOUND を返します。
• 書き込みは成功・失敗にかかわらず、呼び出したキーを実行者として、ストアの監査ログに記録されます。書き込みは冪等ではありません。結果が不確かなリクエストを繰り返す前に、ステータスを読み取って確認してください。

接続状況を読み取る

どちらの読み取りもボディは不要で、200 を返します。返すのは接続の状態、件数、リンクだけです。

{
  "data": {
    "email": {
      "connected": true,
      "count": 2,
      "countUnit": "configured connections",
      "description": "Connection state and configured-connection count only; no credentials are returned.",
      "adminUrl": "/settings/channels/email",
      "connectUrl": "https://admin.shopify.com/store/shop/apps/chatty/embed/settings/channels/email"
    },
    "facebook": {
      "connected": false,
      "count": 0,
      "countUnit": "configured connections",
      "adminUrl": "/settings/channels/facebook",
      "requiresMerchantAction": true,
      "connectUrl": "https://admin.shopify.com/store/shop/apps/chatty/embed/settings/channels/facebook"
    }
  }
}

この例は GET /channels の抜粋です。各チャネルは connected、count、countUnit、description、adminUrl、connectUrl を持ちます。count は設定済みの接続の数で、購読中の数ではありません。メールチャネルは、認証済みのアドレスが 1 つ以上あれば接続済みとして扱われます。

GET /integrations は、連携ごとに 1 つのエントリを返し、connected、description、adminUrl、connectUrl を含みます。tracking には、注文追跡プロバイダーが設定されている場合、provider も含まれます。connected の条件やレスポンスのキーが独自のプロバイダーもあります。プロバイダーごとの動作をご覧ください。

requiresMerchantAction: true は、Chatty admin でマーチャント本人が接続を完了する必要があることを示します。connectUrl に案内してください。API からそのサインインを開始することはできません。ストアが見つからない場合は 404 NOT_FOUND を返します。

GET /channels が返すのは件数で、チャネル ID ではありません。ページ、Instagram アカウント、電話番号、メールチャネルの ID は、Chatty admin で確認するか、メールチャネルの作成時に返された ID を保管してください。

チャネルの設定

すべてのルートに settings.integrations:write が必要で、特に記載がなければ 200 を返します。

• subscribed は、接続済みの 1 つのページまたは Instagram アカウントについて、メッセージの処理をオン・オフします。接続は解除されません。
• catalogOrderEnabled は、1 つの電話番号についてカタログ注文の処理をオン・オフします。レスポンスは、アクセストークンと PIN を除いた保存済みの電話番号レコードです。例は抜粋です。
• DELETE /channels/facebook は、ストアに接続されているすべてのページと、それらのページに紐づく Instagram アカウントを切断します。1 つのページや 1 つの Instagram アカウントだけを切断するルートはありません。切断できないページがある場合、ルートは 502 と "Some Facebook pages could not be disconnected" を返します。すでに削除されたページは削除されたままで、リクエストを繰り返しても問題ありません。
• DELETE /channels/whatsapp/{phoneId} は 1 つの電話番号を削除します。その番号がビジネスアカウントの最後の番号だった場合は、アカウントの購読も解除されます。
• 削除したページ、Instagram アカウント、電話番号を再接続するには、admin でのマーチャントの操作が必要です。

エラー: 404 NOT_FOUND(Page not found、Instagram account not found、Phone number not found)、ボディが無効な場合は 400 VALIDATION_FAILED。

メールチャネル

email は有効なアドレスが必要で、小文字で保存されます。provider は 1〜100 文字の自由記述のラベルで、メールサービスの名前などを入れます。createMode は conversation または ticket で、PATCH で変更できるのはこのフィールドだけです。新しいアドレスは未認証で始まり、admin での設定どおりに転送メールが届くと認証済みになります。削除するとチャネルはすぐに削除されます。

Free プランでは、すでにメールチャネルが 1 つあるストアは追加できず、403 FORBIDDEN を返します。既存のアドレスと一致する場合(ドットやプラス記号によるバリエーションを含む)は、409 CONFLICT と Email address is duplicated を返します。不明な ID は 404 NOT_FOUND を返します。

recheck ルートは、ストアのカスタム送信ドメインの DNS レコードを再確認し、そのレコードを返します。

{"success":true,"data":{"domain":"example.com","dkimStatus":"PENDING","dkimTokens":["token1","token2","token3"],"dmarcPolicy":"none","permanentReason":"","shopCount":1,"dkimRecheckAt":"2026-10-23T08:00:00.000Z"}}

この例は抜粋です。dkimStatus は PENDING、SUCCESS、FAILED のいずれかです。dkimTokens は、公開する DNS の値です。認証済みのカスタム送信ドメインがないストアは、404 NOT_FOUND と Sender domain not found を返します。前回の recheck から 60 秒以内に再実行すると、429 RATE_LIMITED を返し、Retry-After ヘッダーと、秒数を示すトップレベルの retryAfter が付きます。

連携

4 つのルートすべてに settings.integrations:write が必要です。{app} はその操作に対応している必要があり、対応していない場合は 400 INVALID_PARAMS と This integration does not support the requested operation を返します。不明な {app} は 400 VALIDATION_FAILED を返します。

対応プロバイダー

認証情報は、以下にリンクしたプロバイダー自身のドキュメントに従って取得してください。

各認証情報の取得方法：

• Klaviyo private API key (opens in a new tab)
• Discord webhook URL (opens in a new tab)
• 17TRACK security key (opens in a new tab)

「admin のみ」の接続は、プロバイダーのサインインまたはペアリングを使います。マーチャントを GET /integrations の connectUrl に案内してください。注文追跡プロバイダー自体は、これらのルートでは書き込めません。

プロバイダーごとの動作：

接続

POST /integrations/{app} は、まずプロバイダーで認証情報を確認し、その後に保存します。再度接続すると、保存済みの認証情報が置き換えられます。ボディには、そのプロバイダーの認証情報フィールドを指定します。

curl -X POST 'https://app.chatty.net/v1/integrations/{app}' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"<credential field>":"..."}'

成功すると {"success":true,"data":...} と 200 を返します。data に認証情報は含まれません。プロバイダーが拒否した認証情報は 400 を返します。正確なコードはプロバイダーごとの動作をご覧ください。

更新と確認

PATCH /integrations/{app} はプロバイダーの設定を変更し、認証情報を除いた保存済みレコードを返します。POST /integrations/{app}/verify は認証情報を確認するだけで、何も保存しません。対応するプロバイダー、ボディ、上限は上の表をご覧ください。

切断

DELETE /integrations/{app} はボディ不要です。対応している場合はプロバイダー側で認証情報を失効させ、その後に保存済みの認証情報を消去します。繰り返しても問題ありません。レスポンスは {"success":true} か、認証情報を除いた消去後のレコードで、例は {"success":true,"data":{"id":"integration_123","isConnected":false}} です。「admin のみ」のプロバイダーを再接続するには、再度マーチャントの操作が必要です。

エラー

MCP では、get_channels と get_integrations が状況を読み取り、manage_integrations が API キーでこれらの書き込みを行います。MCP ツールリファレンスを参照してください。