ja
API Reference
Overview
💬無料相談を予約

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 APIChatty が収集した連絡先の名前、メールアドレス、チャネル、注文数、購入総額、チャット履歴情報から、必要なフィールドだけ取得します。書き込みはできません。読み取り専用で、メッセージ本文は返しません。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 APIPro または PlusはいX-Api-Key: sk_...キーごとに 1 分間 120 リクエスト、IP ごとに 1 分間 300 リクエスト
Public APIPro または Plusはいスコープを明示した X-Api-Keyキーごとに 1 分間 120 リクエスト、IP ごとに 300 リクエスト。AI への質問はさらにキーごとに 1 分間 20 回
WebhooksPro または Plusはい購読管理に X-Api-Key: sk_... を使用ストアごとに 10 購読。配信のタイムアウトは 10 秒。約 9 時間で最大 7 回試行
GraphQL Customer APIPro または Plusはいx-api-id と x-api-secret読み取り専用。拒否されたリクエストも 200 と errors 配列を返し、401 は返しません
MCP serverPro または 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 をクリックします。

Key name フィールドと Generate key ボタンがある Manage keys パネル

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

新しいキーの全文と、今すぐコピーするよう案内するバナー

!

ページを離れる前にキーをコピーしてください。 Chatty はハッシュのみを保存するため、キー全文を再表示することはできません。失った場合は、そのキーを削除して新しいキーを作成してください。

ストアごとに最大 5 つの有効なキーを保持できます。連携ごとにキーを作成すると、他の連携を止めずに特定のキーだけを削除できます。

ⓘ

新しいキーが使えるようになるまで最大 30 秒かかります。削除したキーは次のリクエストから使えなくなります。 作成直後の最初のリクエストで 401 が返ることはあります。コードの問題を調べる前に、少し待って再試行してください。

ⓘ

キーの作成と管理には、Pro または Plus プランの admin 権限が必要です。他のプランでは、パネルの代わりにアップグレードリンク付きの案内が表示されます。

App ID を確認する

App ID は同じパネルの上部にあります。ツールによっては Client ID と呼ばれます。ストアを識別する値で、連携によってはキーと併せて必要になります。

Manage keys パネル上部の App 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 サポートチームにお問い合わせください。実現したい操作、その操作を行う場所(ストアフロント、サーバー、他のツール)、開発者に依頼できるかをお伝えいただければ、適切なページをご案内できます。