API Reference
この機能をご利用いただける方
- Storefront SDK はすべてのプランで利用でき、キーは不要です。
- GraphQL Customer API、Chat Conversations API、Webhook、MCP には API キーを使用します。API キーを作成できるのは Pro または Plus プランの管理者です。Public API にはスコープを明示したキーを使用します。マーチャント向け MCP は OAuth でも利用できます。
はじめに
Chatty を他のシステムと連携する方法は 7 つあり、それぞれ用途が異なります。目的に合わない方法を選ぶと、コード自体は動いても必要な操作を実現できません。
まず以下の 2 つの表と、よくある選び間違い を確認してください。開発前に数分確認しておくと、作り直しを避けられます。
自分で進められる範囲。 API キーはコードを書かずに短時間で作成できます。以下の API キーの作成 に従ってください。その後は連携先によって異なります。Chatty の API キーを入力する設定画面がある場合は、そこにキーを貼り付ければ完了です。ない場合は Chatty を呼び出すコードが必要なため、開発者に依頼してください。
コードを書かずに使える連携をお探しの場合は、Klaviyo、Zendesk、Joy をご覧ください。
それぞれでできること
| 方法 | できること | できないこと | 詳細 |
|---|---|---|---|
| 標準の連携機能 | Klaviyo、Zendesk、Joy、Gorgias、Powerful Contact Form、SEA Survey、Shopify 以外のウェブサイトと連携します。アプリ内のフォームで設定できます。 | 各アプリのガイドに記載されていない操作。独自に機能を拡張することはできません。 | Integrations |
| Storefront SDK | ストアフロントのウィジェットを開閉し、メッセージの事前入力や送信、顧客・カート情報の受け渡し、訪問者のチャット操作への対応ができます。 | 過去の会話の取得、サーバー上での実行、アプリに保存された設定の変更。購入者のブラウザー内でのみ動作します。 | Storefront SDK |
| Chat Conversations API | 独自のシステムから会話やメッセージの一覧・詳細取得、返信、解決、担当者の割り当て、タグ・メモ・属性の追加、顧客・メンバー・タグの取得ができます。 | イベントの自動通知やウィジェット設定の変更。リクエストに応じて結果を返します。各エンドポイントに対応したキーの権限が必要です。 | Chat Conversations API |
| Public API | 設定、ナレッジ、顧客、会話、チーム、チャンネル、連携、翻訳を管理し、データのエクスポートや分析の取得、メールやファイルの送信を行い、保存した会話の文脈を引き継いで AI に質問できます。 | スコープのない従来のキーでは利用できません。Chat Conversations API とはベースパスが異なります。 | Public API |
| Webhooks | メッセージ、会話、顧客プロフィールに関する 11 種類のイベントを、発生時にサーバーへ通知します。配信ログと再配信にも対応しています。 | 履歴の取得や返信。返信にはサーバーから Chat Conversations API を呼び出します。 | Webhooks |
| GraphQL Customer API | Chatty が収集した連絡先の名前、メールアドレス、チャネル、注文数、購入総額、チャット履歴情報から、必要なフィールドだけ取得します。 | 書き込みはできません。読み取り専用で、メッセージ本文は返しません。 | GraphQL Customer API |
| MCP server | 独自のボットや Claude などの AI アシスタントが、ストアのツールを見つけ、商品・注文・FAQ を検索し、会話に返信できます。 | 汎用 API としての利用。アシスタントが使えるのは、スコープ、認証方式、有効な機能で許可されたツールのみです。 | MCP server |
すべての API に共通する内容は、認証情報の仕組みを説明する Authentication と、リクエスト失敗時の対処を説明する Errors and rate limits をご覧ください。
目的から選ぶ
| 目的 | 使用するもの |
|---|---|
| Chatty のガイドがあるツールと連携する | 標準の連携機能 — コードもキーも不要 |
| 会話をヘルプデスク、データベース、スプレッドシートにコピーする | Chat Conversations API |
| 新しいメッセージを受信したらすぐに処理する | 受信には Webhooks、返信には Chat Conversations API |
| チームが普段使っているツールから顧客に返信する | Chat Conversations API |
| 独自のボタンでチャットボックスを開く、メッセージを事前入力する | Storefront SDK |
| ログイン中の顧客、カート、表示中の商品をチャットに渡す | Storefront SDK |
| 連絡先を CRM、メール配信ツール、CSV にエクスポートする | GraphQL Customer API、またはメールで届く CSV には顧客エクスポート |
| 独自の AI アシスタントに会話の読み取りと返信を任せる | MCP server |
| チャットの件数と結果をレポートにする | 作成済みのレポートには Analytics、会話には Chat Conversations API、顧客には GraphQL Customer API |
| Shopify ストア以外のウェブサイトに Chatty を追加する | ウェブサイト連携 |
よくある選び間違い
以下の組み合わせは似ていますが、用途が異なります。
Chat Conversations API と Webhooks
API はリクエストに応じて結果を返し、Webhook はイベント発生時に通知します。顧客のメッセージから数秒以内に処理したい場合、API の定期的なポーリングでは、頻度が高すぎると制限に達し、低すぎると処理が遅れます。message.created を購読し、詳細の取得や返信が必要なときに API を呼び出してください。
Storefront SDK と Chat Conversations API
SDK は購入者のブラウザーで動作し、その購入者のウィジェットだけを操作します。API はサーバーから使い、ストア全体の会話を扱います。履歴や他の顧客の情報、訪問者がいない間の処理には API を使用します。ページ上のウィジェットの動作には SDK を使用します。
MCP server と Chat Conversations API
どちらも返信できますが、呼び出す操作を決める主体が異なります。MCP では AI アシスタントがツールの中から使うものを選びます。API ではコードが処理を決め、決まったパスを呼び出します。AI モデルを使わない処理には、MCP を挟む必要はありません。
GraphQL Customer API と Chat Conversations API
どちらにも顧客が登場しますが、GraphQL が返すのは顧客情報と集計値だけです。読み取り専用で、メッセージ本文はありません。Chat Conversations API は会話とメッセージ自体を返します。購入者に関する情報をすべて取得したい場合は、通常は両方が必要です。
標準の連携機能と独自開発
開発範囲を決める前に Integrations を確認してください。連携先のガイドがすでにあれば、アプリ内のフォームで設定でき、開発は不要です。
公開 API とブラウザー内のパス
ブラウザーの管理画面の Inbox は、管理者セッションで認証された /api/chat/... 配下のよく似たパスを呼び出します。これらは公開 API ではなく、API キーでは使えません。公開パスに /api は付きません:https://app.chatty.net/chat/conversations。
プラン、認証情報、制限
| 方法 | プラン | 開発者が必要か | 認証情報 | 主な制限 |
|---|---|---|---|---|
| 標準の連携機能 | 各アプリのガイドを参照 | いいえ | なし | アプリ内で設定 |
| Storefront SDK | すべて | テーマへの JavaScript 追加に必要 | なし | ウィジェットが読み込まれたページでのみ動作 |
| Chat Conversations API | Pro または Plus | はい | X-Api-Key: sk_... | キーごとに 1 分間 120 リクエスト、IP ごとに 1 分間 300 リクエスト |
| Public API | Pro または Plus | はい | スコープを明示した X-Api-Key | キーごとに 1 分間 120 リクエスト、IP ごとに 300 リクエスト。AI への質問はさらにキーごとに 1 分間 20 回 |
| Webhooks | Pro または Plus | はい | 購読管理に X-Api-Key: sk_... を使用 | ストアごとに 10 購読。配信のタイムアウトは 10 秒。約 9 時間で最大 7 回試行 |
| GraphQL Customer API | Pro または Plus | はい | x-api-id と x-api-secret | 読み取り専用。拒否されたリクエストも 200 と errors 配列を返し、401 は返しません |
| MCP server | Pro または Plus | はい | X-App-Id と Authorization: Bearer sk_... | 権限、認証方式、有効な機能によってツールが絞り込まれます |
ストアごとに最大 5 つの有効な API キーを保持できます。同じ sk_ キーを Chat Conversations API、Webhook、MCP、GraphQL で使えますが、指定するヘッダーが異なります。詳しくは Authentication をご覧ください。
API キーを作成する
管理者としてログインし、Settings → General → Manage keys で API キーを管理します。
API キーの作成
Permissions で Read conversations や Read customers など、キーに必要な権限を選択します。何も選択していないキーは、Chat Conversations API と Webhook のすべての呼び出しで拒否されます。次に Key name に名前を入力します。Zendesk sync のように、使用するツールが分かる名前にしてください。最大 50 文字です。最後に Generate key をクリックします。

作成したキーが一覧に表示され、sk_ の値全体を確認できます。

ページを離れる前にキーをコピーしてください。 Chatty はハッシュのみを保存するため、キー全文を再表示することはできません。失った場合は、そのキーを削除して新しいキーを作成してください。
ストアごとに最大 5 つの有効なキーを保持できます。連携ごとにキーを作成すると、他の連携を止めずに特定のキーだけを削除できます。
新しいキーが使えるようになるまで最大 30 秒かかります。削除したキーは次のリクエストから使えなくなります。 作成直後の最初のリクエストで 401 が返ることはあります。コードの問題を調べる前に、少し待って再試行してください。
キーの作成と管理には、Pro または Plus プランの admin 権限が必要です。他のプランでは、パネルの代わりにアップグレードリンク付きの案内が表示されます。
App ID を確認する
App ID は同じパネルの上部にあります。ツールによっては Client ID と呼ばれます。ストアを識別する値で、連携によってはキーと併せて必要になります。

知っておきたい 2 つの動作
会話一覧の件数が Inbox より少ない場合があります。 一覧にはストアの主要な会話ストアのデータが反映されます。それ以前の古い会話は一覧に含まれませんが、ID を指定して個別に取得できます。照合処理では一覧が完全だと仮定せず、すでに保持している ID を基準にしてください。
送信直後のメッセージがすぐに表示されないことがあります。 Chatty はまずリアルタイム処理用の保存先にメッセージを書き込み、その後で同期します。そのため、書き込み直後の読み取りには含まれない場合があります。一覧にまだないことを、送信失敗と判断しないでください。
Chatty の設定には Settings and features、会話を続けながら AI に質問するには Ask AI、一連の連携手順には CRM 連携の例 をご覧ください。
実装できるもの
連絡先をスプレッドシートにエクスポートする
GraphQL の customers クエリをページ分割して呼び出し、すべての連絡先を取得して CSV に保存します。
購入額の高い顧客をメール配信ツールに同期する
totalSpent で絞り込み、一致する顧客をメール配信ツールの API で送信します。
新しい顧客メッセージをチームに通知する
message.created Webhook を購読し、senderType が customer の場合のみ処理してチームに通知します。
ストアフロントにチャット操作を追加する
SDK を使い、独自のボタンからチャットボックスを開いたり、メッセージを事前入力したりできます。
サポートが必要な場合
どの方法が適しているか迷った場合は、ダッシュボードから Chatty サポートチームにお問い合わせください。実現したい操作、その操作を行う場所(ストアフロント、サーバー、他のツール)、開発者に依頼できるかをお伝えいただければ、適切なページをご案内できます。
Chatty Help Center