公開API Beta

対応が必要な会話を見つける

awaitingReply、unread、unassigned、assigneeId、agentGroupId、snoozed、priority、tagIds で絞り込みます。awaitingReply は社内メモを無視します。unread は認証されたメンバーごとの状態です。unassigned は、チームが割り当てられていても個人の担当者がいないことを意味します。タグは指定したいずれかのIDに一致します。

GET /api/v1/conversations?status=open&awaitingReply=true&compact=true&sort=waitingSince&direction=asc

waitingSince、lastMessageAt、createdAt、またはビジネス上の優先度で、direction に asc または desc を指定して並べ替えます。同順の場合はIDで決まります。絞り込みを省略すると、compact=false と snoozed=any が維持されます。RESTの tagIds はカンマ区切りのIDを受け付け、MCPでは配列も使えます。waitingSince は、最後の返信の後の最初の受信メッセージから始まり、追加のメッセージや社内メモではリセットされません。古いスレッドが再び浮上するよう、Webhookが届かないときでも、この待機キューのスキャンを定期的に実行してください。

受信トレイを読み直さずに追いつく

conversations:read を指定して GET /api/v1/sync を使います。永続フィードには、会話の変更、タグ、メッセージ、連絡先のプロパティ、メモリー、削除の記録が含まれます。各ペイロードにはそれぞれの読み取りスコープも必要です。メッセージ本文には messages:read が、メモリーには contact-memory:read が必要です。制限された認証情報では、許可されたチャネルの分だけが返されます。

1. カーソルなしで開始し、hasMore が false になるまで nextCursor をたどって、そのカーソルを保存します。
2. 初期状態に必要な、現在の会話／連絡先の一覧と履歴を読み取ります。
3. 保存したカーソルから再取得して、読み取り中に起きた変更に追いつきます。各ページを処理してから、nextCursor を保存します。

イベントの id で重複を除外してください。再取得は少なくとも1回の配信を保証するため、後続の処理にも独自の重複対策が必要です。カーソルなしのリクエストは直近1時間分で、完全なスナップショットではありません。イベントは30日間保持されます。HTTP 410 resync_required が返されたら、再度初期化してください。スコープやチャネルへのアクセスを広げた後も初期化してください。limit は最大100、maxBodyChars は最大10,000（デフォルト500）です。compact=true を設定すると、body/bodyTruncated の代わりに、200文字までのメッセージの textPreview/textTruncated フィールドが返されます。Webhookでエージェントを起動できますが、フィードはWebhookを購読していない場合や、Webhookの配信が滞っている場合でも利用できます。

確認結果を一度記録して共有する

調査を繰り返す前に、list_conversation_checks（GET /api/v1/conversations/{conversationId}/checks）を読み取ってください。結果は record_conversation_check（同じパスへのPUT）で、key、result、checkedBy と、カードのIDやURLを示す任意の reference を指定して保存します。例：key=product-version、result=Shopstar Go verified、checkedBy=Engineer、reference=card-X。Sonnyは認証された actorId と checkedAt のタイムスタンプを記録します。同じキーを再利用すると、その確認だけが置き換わります。これは履歴ではなく現在の状態です。読み取りには conversations:read、書き込みには conversations:write が必要で、どちらも会話のチャネルに限定されます。これらの呼び出しで返信が送られたり、販売者が回答済みとして記録されたりすることはありません。

割り当てと一括更新

GET /api/v1/members and /teams（members:read）で、アクティブで割り当て可能なメンバーとチームを確認します。レスポンスには対応状況と実際のチャネルへのアクセスが含まれ、メールアドレスは含まれません。conversations:write を使って、status、priority、assigneeId、agentGroupId、snoozedUntil、snoozedUntilReply、addTagIds、removeTagIds を変更します。

POST /api/v1/conversations/batch
{
  "conversationIds": ["conversation_1", "conversation_2"],
  "updates": { "agentGroupId": "team_1", "assignment": "round_robin" }
}

ラウンドロビンでは、会話のチャネルにアクセスできる対応可能なチームメンバーが選ばれます。対象となるメンバーがいない場合、単一の更新では409が返され、一括処理ではその項目が失敗します。一括処理では最大100個の一意なIDを受け付け、会話ごとにひとつのパッチをアトミックに適用します。{ id, ok, error? } の結果をすべて確認してください。一部の項目が失敗する場合があります。一括処理には現在のリクエスト単位のレート制限が適用され、項目数による重み付けはありません。

Sonny AIと顧客情報を共有する

contact-memory:read/write で、連絡先のメモリーを一覧表示、保存、削除します。contactId と、アクセス可能な sourceId の両方を指定してください。連絡先には、そのソースでの会話が必要です。保存した事実には、アプリと同じ検証、重複の処理、上限が適用され、手動のメモリーとして記録されます。

プロパティの定義は /api/v1/properties で読み取り、値は /api/v1/contacts/{contactId}/properties で読み取り・設定します。MCPでは list_properties、get_contact_properties、set_contact_property を使えます。これらには contacts:read/write と、すべてのチャネルへのアクセスが必要です。propertyId または propertyName のどちらか一方を指定し、文字列の値、またはクリアする場合は null を指定します。テキスト、数値、URL、日付、選択肢の値は、フィールドの定義に照らして検証されます。

PUT /api/v1/contacts/contact_1/properties
{ "propertyName": "Plan", "value": "Pro" }

GET /api/v1/contacts?property[Plan]=Pro

プロパティの絞り込みは、保存された文字列と完全一致で照合します。複数のプロパティを指定した場合は、すべてに一致する必要があります。APIで書き込まれた値は、Co-Pilotと自動応答でAPIのデータとして表示されます。既存の認証済み顧客とソースのルールは引き続き適用されます。通常の手動入力による社内向けのフィールド値は、このAIの文脈から除外されたままです。

チームと同じレポートを読み取る

reporting:read を指定して GET /api/v1/reporting/{kind} を呼び出します。種類は overview、volume、response-times、agents、sources、tags、csat、ai、knowledge、leads、online-hours です。overview は件数、応答時間、CSATをまとめたものです。絞り込みには、period（1〜365日、デフォルト30）、組み合わせで指定する from/to の日付（to は含みません）、granularity（day/month）、source、assigneeId、tagId を使えます。source には all、all-chat、all-email、website:{id}、email:{id} を指定できます。

レポートには、ダッシュボードと同じクエリと現在のアクセス確認が使われます。knowledge は、選択したソース、担当者、タグとは関係なく、日付と許可されたチャネルを使います。online-hours は、アクセス可能なメンバーのワークスペースでのオンライン状況を測定し、会話数はチャネルに限定されたままです。既存の /csat エンドポイントは、独自の csat:read スコープを使い、対象となる母集団が異なる場合があります。

返信や社内メモでファイルを送る

attachments:write を付与し、会話用に最大25MBのファイルをアップロードします。POST /api/v1/attachments には、multipart の file フィールドと conversationId フィールドを指定します。 レスポンスには id と expiresAt が含まれます。1時間以内に、最大10個の attachmentIds を返信またはメモに渡します。各アップロードはあなたのユーザーと会話に紐づき、一度だけ使えます。使われなかったアップロードは、期限切れ後に削除されます。

POST /api/v1/conversations/conversation_1/reply
{ "attachmentIds": ["upload_1"] }

返信には messages:send が、社内メモには messages:write が必要で、社内メモが顧客に届くことはありません。添付ファイルだけのメッセージにも対応しています。メールの返信では、メールのサイズの範囲内でファイルを添付し、残りはダウンロードリンクにします。オフライン時のチャットのメールにはファイルのリンクが含まれます。メールで送られたリンクは添付ファイルが存在する限り使えるため、受信者は後から開けます。メールを転送すると、それらのファイルへのアクセスも共有されます。配信の失敗は emailDeliveryStatus で確認してください。

認可されたメッセージの読み取りには、downloadUrl、downloadExpiresAt、aiStatus、aiDescription、aiExtractedText に加え、リンクされた動画（Loom、Vimeoなど）の videoTranscripts が含まれます。ダウンロードリンクの有効期間は15分です。新しいリンクが必要な場合は、メッセージを読み直してください。API/MCPで新しくアップロードしたファイルは非公開のストレージに保存されます。以前の添付ファイルは公開のままで、access=legacy_public と示され、元のURLは期限切れになりません。ワークスペースでSonny AIが有効な場合、メッセージを読み取るとその画像の読み取りが始まります。画像の読み取りと動画の文字起こしは、メッセージの到着後まもなく完了します。処理中のものがある間、レスポンスは readsInProgress で始まり、その nextStep に次に行うべき呼び出しが正確に示されます。waitSeconds（最大30）を指定すると、1回のリクエストで完了を待てます。顧客向けのウィジェットとリアルタイムのメッセージには、抽出内容や文字起こしは含まれません。