Conversations

各パスは Public API base URL に追加してください。すべてのリクエストに X-Api-Key、JSON の書き込みには Content-Type: application/json を付けます。アップロードには multipart を使います。Chat Conversations API の既存の /chat ルートはそのまま利用できますが、会話の作成、アップロード、削除は Public API 専用です。

メールの会話を開始する

POST /conversations — conversations:write、Pro / Plus。ストアごとに 1 時間 60 回までで、MCP と上限を共有します。

送信するメールの会話を開始します。匿名のストアフロントチャットや、WhatsApp テンプレートによる新規会話は作成しません。最初のメッセージを省略してもメールアドレスは必須です。

curl -X POST 'https://app.chatty.net/v1/conversations' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","memberId":"member_123","subject":"Your order","message":"Your order is ready."}'

201 レスポンスには新しい ID が含まれます。最初のメッセージも指定した場合は、保存したメッセージも返します。以下は一部を抜粋した例です。

{"data":{"conversationId":"conv_123","message":{"id":"msg_123","text":"Your order is ready.","isAdmin":true,"memberId":"member_123"}}}

メッセージもファイルもない場合は {"data":{"conversationId":"conv_123"}} を返し、顧客向けの最初のメッセージは送信しません。この操作で Shopify customer は作成されません。

メールアドレス、件名、メンバー、メッセージ、添付情報が不正な場合は 400 INVALID_PARAMS、ストアが存在しない場合は 404 NOT_FOUND を返します。共通の認証、スコープ、レート制限エラーは後述します。

{"error":{"code":"SEND_FAILED","message":"Message could not be sent","conversationId":"conv_123"}}

添付ファイルをアップロードする

POST /conversations/{id}/uploads — conversations:write、Pro / Plus。キーと同じストアの会話が必要です。ストアごとに 1 時間 60 バッチまでで、MCP と上限を共有します。

curl -X POST 'https://app.chatty.net/v1/conversations/conv_123/uploads' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -F '[email protected];type=application/pdf'

multipart の boundary は HTTP クライアントに設定させてください。1–10 ファイルを送信でき、1 ファイル最大 20 MiB、multipart リクエスト全体で最大 25 MiBです。アップロードだけではメッセージを送信しません。バッチ全体が成功した場合のみ、201 と添付情報を返します。

{"data":[{"id":"file_123","url":"livechat/shop_123/conversations/file_123.pdf","mimeType":"application/pdf","title":"invoice.pdf","altText":""}]}

これは添付情報の例です。実際には自分のストアに対して返された値をそのまま使ってください。保存の一部または全部が失敗すると、部分的な成功ではなく 502 UPLOAD_FAILED を返します。一部のファイルはすでに保存済みの場合があるため、再試行前に確認してください。会話が存在しない、または別のストアに属する場合は 404 NOT_FOUND、multipart、サイズ、件数、MIME が不正な場合は 400 INVALID_PARAMS です。

JPEG、PNG、GIF、WebP、PDF、DOC/DOCX、XLS/XLSX、PPT/PPTX、プレーンテキスト、CSV、対応する動画・アーカイブ形式を受け付けます。SVG は受け付けません。指定できる MIME 値は次のとおりです。

image/jpeg, image/png, image/gif, image/webp
application/pdf, application/msword
application/vnd.openxmlformats-officedocument.wordprocessingml.document
application/vnd.ms-excel, application/x-excel, application/x-msexcel, application/x-vnd.ms-excel
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
application/vnd.ms-powerpoint
application/vnd.openxmlformats-officedocument.presentationml.presentation
text/plain, text/csv
video/mp4, video/webm, video/quicktime, video/x-msvideo, video/3gpp, video/x-matroska, video/mpeg, video/ogg
application/zip, application/x-rar, application/x-rar-compressed, application/vnd.rar
application/x-7z, application/x-7z-compressed, application/gzip, application/x-gzip
application/x-bzip, application/x-bzip2, application/x-tar, application/x-tar-gz, application/x-tgz
application/x-compress, application/x-compressed, application/x-lzip, application/x-xz
application/octet-stream, application/x-zip, application/x-zip-compressed, application/zip-compressed

返信や添付ファイルを送信する

POST /conversations/{id}/messages — conversations:write、Pro / Plus。同じリクエストを POST /chat/conversations/{id}/messages にも送信できます。

各添付情報には url と対応する mimeType が必要です。任意の id、title、altText は、指定する場合は文字列である必要があります。任意の外部 URL や別のストアのファイルは拒否されます。このストアの Chatty アップロードキーか対応する CDN URL、または同じ Shopify ストアの Shopify Files URL を受け付けます。所有権は会話単位ではなくストア単位で確認します。自分でパスを組み立てず、返された添付情報を再利用してください。

curl -X POST 'https://app.chatty.net/v1/conversations/conv_123/messages' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"memberId":"member_123","text":"Here is your invoice.","files":[{"id":"file_123","url":"livechat/shop_123/conversations/file_123.pdf","mimeType":"application/pdf","title":"invoice.pdf","altText":""}]}'

成功時は 201 を返し、data に ID とファイルを含む保存済みメッセージが入ります。読み取りでは保存済みのアップロードキーを利用可能な URL に変換します。内容、メンバー、添付情報が不正なら 400 INVALID_PARAMS、会話を取得できない場合は 404 NOT_FOUND です。既存の Messenger、Instagram、WhatsApp、メールの会話への返信は、そのチャネルで配信されます。対応する 24 時間の送信可能期間外では 409 CHANNEL_UNAVAILABLE になる場合があります。アップロード成功は、チャネルがすべての添付形式を配信できる保証ではありません。

内部メッセージは顧客へ送信されません。顧客向けの返信は message.created を発生させるため、data.senderType を確認し、自分の agent や bot メッセージに返信しないようにしてください。メッセージ送信に冪等性キーはありません。

会話とメッセージを読み取る

以下のルートはすべて conversations:read、Pro / Plus が必要で、リクエストボディはありません。成功時は 200 を返します。例は抜粋または空の結果です。各項目の詳細は Objects and fields をご覧ください。

一覧は channel、assigneeId（または unassigned）、isRead、複数の tag、customerUuid、email、dateFrom、dateTo、cursor にも対応します。チャネルは online_store、email、facebook、instagram、whatsapp で、会話の開始元に一致するものを選びます。タグはいずれかが一致すれば対象です。日付のみの境界は作成日時を対象とし、終了日は終日を含みます。タイムゾーン付き ISO タイムスタンプは最終メッセージ日時を対象に境界値を含めます。上下限は同じ形式を使ってください。フィルターの説明 もご覧ください。

ページ分割には paging.nextCursor を使います。会話は既定 20 件・最大 100 件、メッセージは既定 50 件・最大 100 件、関連会話は既定 6 件・最大 50 件です。メッセージの order は asc または desc で、既定は asc です。不正なフィルター、ページ指定、カーソルは 400 INVALID_PARAMS を返します。会話やメッセージが存在しない、または別のストアに属する場合は 404 NOT_FOUND、要約が未生成の場合も 404 です。

会話一覧は移行済みのレコードが対象ですが、詳細読み取りでは古いレコードも ID で取得できます。メッセージ一覧は削除済みを除外しますが、単体読み取りでは isDeleted: true を返す場合があります。閲覧ページはセッション単位で、直近 50 ページを約 24 時間保持し、空の場合もあります。

状態、担当者、入力中表示

次の 4 つの POST ルートには conversations:write、Pro / Plus が必要で、成功時は 200 を返します。会話が存在しない、または別のストアに属する場合は 404 NOT_FOUND、状態やメンバーの入力が不正なら 400 INVALID_PARAMS です。

割り当てを解除するには、/assign に {"memberId":null} を送ります。data に同じ値を返します。memberId の省略や空文字は解除にならず、400 INVALID_PARAMS を返します。メンバー ID は GET /members（conversations:read、Pro / Plus、ボディなし、空なら 200 {"data":[]}）で確認してください。

入力中表示には表示名の name も指定できます。サーバー側に有効期限はないため、入力が止まったら active: false を送信してください。入力中表示は一時的な通知で、永続的な操作記録は作成しません。

タグ、チェックリストのメモ、属性

以下は、別途説明するタグ一覧の読み取りを除き、conversations:write、Pro / Plus が必要です。リクエストとレスポンスの例を示します。メモと属性のオブジェクトは抜粋です。

タグは追加して重複を除きます。100 文字を超えるタグは除外し、有効なタグがなければ 400 INVALID_PARAMS を返します。ストアの会話タグ一覧は GET /tags（conversations:read、Pro / Plus、ボディなし、空なら 200 {"data":[]}）で読み取れます。顧客タグ とは別です。

チェックリストのメモは 150 文字までで、isNote を付ける内部メッセージとは別です。属性名は 255 文字、値は 1,000 文字までで、同じ名前を作成すると更新になります。不正な入力は 400 INVALID_PARAMS、会話、メモ、属性がなければ 404 NOT_FOUND です。すでにないタグの削除は、何も変更せず成功します。

会話とトランスクリプトをエクスポートする

どちらのルートも conversations:read、Pro / Plus で、ファイルはレスポンスで返します。メールでは送信されません。

POST /conversations/export は、最大 limit 件（1～1,000、デフォルト 1,000）の会話を 1 ページ分、更新が新しい順に返します。オフセットはありません。それ以上エクスポートするときは、日付フィルターを絞って再度呼び出してください。ボディが空の場合はデフォルトでエクスポートします。ボディと filters は厳格で、未知のフィールドは 400 VALIDATION_FAILED を返します。

配列は最大 100 個の値を持て、各値は 500 文字までです。format は json（デフォルト）または csv です。

{
  "success": true,
  "data": {
    "totalCount": 1342,
    "pagination": {"limit": 1000, "offset": 0, "hasMore": true},
    "conversations": [{"id": "conv_123", "firestoreId": "conv_123", "pgConvoId": "1234567890", "channels": ["chatbox"], "tags": []}]
  },
  "exportInfo": {"format": "json", "exportedAt": "2026-10-23T08:00:00.000Z", "totalExported": 1000, "totalAvailable": 1342}
}

JSON の例は抜粋で、各会話には保存されているフィールドが camelCase で含まれます。totalAvailable は一致したすべての件数、totalExported は返した行数です。CSV は conversations-YYYY-MM-DD.csv という名前の添付ファイルとして送信され、列は ID、Customer Name、Email、Status、Tags、Channels、Member、Created At、Updated At、Resolved At です。すべてのセルは引用符で囲まれ、スプレッドシートが数式として実行しうるセルは ' から始まります。

GET /conversations/{id}/transcript は、1 件の会話の顧客向けメッセージを返します。format は txt（デフォルト）または csv で、それ以外のクエリパラメータは 400 VALIDATION_FAILED を返します。テキストの行は <time> | <sender>: <message> の形式です。CSV の列は Time、Sender、Message です。内部メモ、アクティビティ行、リマインダーは含まれません。添付ファイルは Sent 2 files のような行で表示されます。存在しない会話や他のストアの会話は 404 NOT_FOUND を返します。

エクスポートに時間がかかりすぎると 502 UPSTREAM_TIMEOUT、データストアが利用できないと 502 UPSTREAM_UNAVAILABLE を返します。どちらも何も変更しないため、安全に再試行できます。

会話を削除する

DELETE /conversations/{id} — conversations:delete、Pro / Plus。ボディは不要です。conversations:write だけでは削除できません。

curl -X DELETE 'https://app.chatty.net/v1/conversations/conv_123' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

{"data":{"id":"conv_123","deleted":true}}

成功時は 200 です。会話が存在しない、または別のストアに属する場合は 404 NOT_FOUND、削除可能な Firestore レコードがない場合は 404 CONVERSATION_NOT_DELETABLE を返します。成功すると空の data を持つ conversation.removed が発生します。削除成功後に繰り返すと 404 になります。

共通エラーと再試行

各エンドポイントは、処理開始前に認証やスコープの確認で拒否する場合があります。Public API のバージョン検証と共通のレート制限も適用されます。

作成・アップロードの検証では 400 INVALID_PARAMS または 400 VALIDATION_FAILED、保存・配信の失敗では 502 UPLOAD_FAILED または 502 SEND_FAILED を返す場合があります。再試行前に各操作の説明を確認してください。予期しない失敗はサーバーエラーになるため、サポート用にレスポンスを保存してください。タイムアウトしても書き込みが失敗したとは限りません。作成や送信を繰り返す前に、保存済みのリソースを確認してください。