オムニチャネルメッセージング

オムニチャネルメッセージングでは、Sonzai エージェントが Meta チャネル上で会話できます。Web やモバイルのチャットで使うものと同じパーソナリティ、メモリ、会話履歴が使われます。チャネルを一度接続し、エージェント人格にマッピングすれば、Conversations API でスレッドの確認、イベント購読、ライブ会話のテイクオーバーができます。

Meta チャネルを接続する

セットアップ方法は2つあります。

• Bring Your Own App — 主な方法です。Meta app、ビジネスアセット、Webhook verify token、access token をあなたが作成して所有します。Sonzai は提供されたチャネル認証情報を保存し、その app 経由でメッセージを配信します。
• Embedded Signup — Sonzai コンソールから使える簡単なワンクリックフローです。現在ロールアウト中です。テナントで表示されており、Meta app を自分で管理する必要がない場合に使用してください。

Bring Your Own App

この手順は WhatsApp、Facebook Messenger、Instagram に共通です。

1. Meta for Developers で、このチャネルに使う app を作成または開きます。
2. 対象チャネルの製品を追加します：WhatsApp、Messenger、Instagram。
3. 必要なビジネスアセットを接続します。
   • WhatsApp：WhatsApp Business Account と電話番号。
   • Messenger：メッセージを受信する Facebook Page。
   • Instagram：Facebook Page に接続された Instagram professional account。
4. Meta 製品の Webhook 設定で、callback URL を https://api.sonz.ai/webhooks/channels/meta に設定します。
5. verify token を作成します。テナントが所有するランダムな文字列を使い、安全に保存してください。同じ値を Meta と Sonzai コンソールの両方に貼り付けます。
6. 選択した製品のメッセージ配信フィールドを Webhook に購読させます。
7. 選択したアセットに対する権限を持つ access token を生成します。Meta が対応している場合は、長期有効な system user token または page token を使います。
8. Sonzai コンソールで Channels を開き、Add channel を選択してから、Meta チャネルと Bring Your Own App を選びます。
9. コンソールが求める値を貼り付けます。
   • App ID
   • App Secret
   • WhatsApp の Phone Number ID、Messenger の Page ID、または Instagram の Instagram Account ID
   • Access Token
   • Verify Token
10. エージェントのルーティング先を選択し、チャネルを保存して、接続済みアカウントからテストメッセージを送信します。

チャネルルーティング

各チャネルはエージェント人格にマッピングされます。1つのチャネルの全メッセージを単一のデフォルトエージェントへルーティングすることも、コンソールで tier が有効な場合は tier ごとにトラフィックを分けることもできます。たとえば WhatsApp サポートチャネルでは、無料 tier のユーザーをトリアージ人格へ、有料 tier のユーザーをコンシェルジュ人格へルーティングできます。

メッセージが設定済みのチャネルまたは tier に一致しない場合、Sonzai はそのチャネルのデフォルトエージェントを使用します。デフォルトエージェントが未設定の場合、会話は未ルーティングのままとなり、conversation.unrouted Webhook イベントが送信されます。バックエンド側でルートを割り当てたり、オペレーターに通知したりできます。

会話と可観測性

Conversations API を使うと、WhatsApp、Messenger、Instagram、およびテナントに接続された他のチャネルを横断して、スレッドの一覧表示、検索、確認、ストリーミングができます。

スレッドの一覧表示と検索

REST：

curl -H "Authorization: Bearer $SONZAI_API_KEY" \
  "https://api.sonz.ai/conversations?channel=whatsapp&status=open&q=refund&limit=25"

SDK：

const conversations = await client.conversations.list({
channel: "whatsapp",
status: "open",
query: "refund",
agentId: "agent-id",
limit: 25,
});

for (const thread of conversations.items) {
console.log(thread.id, thread.channel, thread.agentId, thread.lastMessageAt);
}

スレッドを確認する

REST：

curl -H "Authorization: Bearer $SONZAI_API_KEY" \
  "https://api.sonz.ai/conversations/conversation-id"

curl -H "Authorization: Bearer $SONZAI_API_KEY" \
  "https://api.sonz.ai/conversations/conversation-id/messages?limit=50"

SDK：

const thread = await client.conversations.get("conversation-id");
const messages = await client.conversations.messages("conversation-id", {
limit: 50,
});

console.log(thread.participant, messages.items.at(-1)?.text);

ライブ会話をストリーミングする

コンソール、CRM、サポートデスクがポーリングなしでライブ更新を必要とする場合は、stream を使います。

for await (const event of client.conversations.stream("conversation-id")) {
console.log(event.type, event.message?.text);
}

Webhook イベント

バックエンドで永続的な可観測性やワークフロー自動化が必要な場合は、conversation イベントを購読します。イベントを処理する前に Sonzai Webhook 署名を検証してください。署名モデルは Webhook と通知 ページと同じです。

イベントペイロードには、conversation ID、channel、ルーティング済みの場合の agent ID、参加者識別子、イベントに関係するメッセージまたは失敗詳細が含まれます。Webhook 配信だけを唯一の正としないでください。イベント受信後は Conversations API でスレッドを再取得します。

人間によるテイクオーバー

人間によるテイクオーバーは、ライブ会話における自律的なエージェント返信を一時停止し、オペレーターが同じエージェント人格を通じて返信できるようにします。エンドユーザーには引き続きチャネルのアイデンティティから送られたメッセージとして見え、エージェントは transcript をメモリに保持します。テイクオーバーを解除すると、エージェントはその間にユーザーとオペレーターが話した内容を覚えています。

REST フロー

# 1. ライブ会話をテイクオーバーする
curl -X POST "https://api.sonz.ai/conversations/conversation-id/takeover" \
  -H "Authorization: Bearer $SONZAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operator_id":"op-123","reason":"billing escalation"}'

# 2. エージェント人格として返信する
curl -X POST "https://api.sonz.ai/conversations/conversation-id/messages" \
  -H "Authorization: Bearer $SONZAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operator_id":"op-123","text":"I can help check that invoice now."}'

# 3. 自律エージェント処理へ戻す
curl -X DELETE "https://api.sonz.ai/conversations/conversation-id/takeover" \
  -H "Authorization: Bearer $SONZAI_API_KEY"

SDK フロー

await client.conversations.takeOver("conversation-id", {
operatorId: "op-123",
reason: "billing escalation",
});

await client.conversations.sendAsAgent("conversation-id", {
operatorId: "op-123",
text: "I can help check that invoice now.",
});

await client.conversations.release("conversation-id", {
operatorId: "op-123",
});