CRM 連携の例

このワークフローでは、顧客のメッセージを CRM に取り込み、担当者が返信できるようにします。担当者は別の AI 会話を使い、続きの返信の下書きも作成できます。Webhook の受信処理から自動的に AI を呼び出したり、すべての回答を顧客に送り返したりする流れではありません。

1. イベントを登録する

curl -s -X POST "https://app.chatty.net/chat/webhooks" \
  -H "X-Api-Key: $CHATTY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://crm.example.com/chatty/events","events":["message.created","customer.updated","conversation.updated"]}'

新しい URL を登録した場合は、201 レスポンスの data.id と data.secret を保存します。登録済みの URL は 200 を返し、シークレットは含まれません。シークレットを失った場合は、購読一覧を取得するのではなく、署名シークレットのローテーション を実行してください。

イベントを受信するたびに、次の処理を行います。

1. Webhooks の手順に従い、未加工のボディを使ってタイムスタンプと署名を検証します。
2. 一意制約を付けて eventId を保存し、処理を永続化されたキューに登録します。重複イベントで CRM メッセージや返信を二重に作成しないようにします。
3. 10 秒以内に 2xx を返します。受信確認を返した後で、保存したイベントを処理します。
4. message.created では顧客のメッセージを取り込みます。返信するかどうかの判定では agent、bot、system を除外します。自分たちが送った返信を新しい問い合わせとして扱わないでください。
5. customer.updated では、data.customerId を使って受信した連絡先フィールドをマージします。このイベントの conversationId: null に注意してください。タグのみ、またはメモのみの変更では発生しません。
6. conversation.updated では、data.detectedEmail と data.detectedPhone を使って、その会話について保持しているメールアドレスや電話番号を更新します。どちらが変わったかは data.changed で分かります。値が null の場合は削除されたことを意味します。顧客がメールアドレスを伝えた時点で、匿名のチャットを CRM の連絡先に紐付けるのに使えます。

Webhook は配信順序やすべてのイベントの到達を保証しないため、読み取り API を使って定期的にデータを照合してください。障害の後は、サブスクリプションの失敗した配信を一覧で確認して再配信してください。ペイロードは 30 日間保持されます。

2. CRM から返信する

担当者の memberId は GET /chat/members で確認します。元のメッセージイベントの会話 ID を使って返信を送信します。

curl -s -X POST "https://app.chatty.net/chat/conversations/conv_123/messages" \
  -H "X-Api-Key: $CHATTY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"memberId":"member_123","text":"Thanks for getting in touch. I can help with that."}'

成功時は 201 を返し、data に保存済みメッセージが入ります。返された ID を CRM に保存してください。409 CHANNEL_UNAVAILABLE の場合は、すぐに再試行せず、チャネルと連絡先を確認します。その他のエラーは Chat API のエラー一覧 をご覧ください。

この返信を送ると、別の message.created が発生し、senderType: "agent" が設定されます。上記のフィルターによってループを防ぎます。書き込みの冪等性キーはないため、ネットワークがタイムアウトした場合は、再送前にメッセージを確認してください。

3. AI に下書きを依頼する

/ai/ask には Public API のベース URL を使用します。保存される別の AI セッションが開始されます。

curl -s -X POST "https://app.chatty.net/v1/ai/ask" \
  -H "X-Api-Key: $CHATTY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Explain the return policy so I can answer a customer."}'

200 の場合は data.answer を担当者に表示し、data.conversationId を CRM スレッドの AI セッション ID として保存します。元のライブチャットの会話 ID である conv_123 とは別です。AI とのやり取りも Chatty にメッセージを作成するため、連携機能が作成した AI セッションは顧客向けの自動処理から除外してください。

4. AI セッションを続ける

ai_conv_123 を手順 3 で取得した実際の ID に置き換えます。

curl -s -X POST "https://app.chatty.net/v1/ai/ask" \
  -H "X-Api-Key: $CHATTY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversationId":"ai_conv_123","message":"What if the customer bought the item on sale?"}'

成功するたびに返された ID を保存します。担当者が回答を確認して採用したら、元のライブチャット ID を使い、手順 2 のメッセージエンドポイントで送信します。/ai/ask は下書きのやり取りを保存しますが、そのライブチャットへ回答を配信することはありません。

5. 利用枠の上限と AI の無効状態に対処する

HTTP ステータスと error.code の両方を確認してください。403 AI_DISABLED と 403 FORBIDDEN では対処方法が異なります。

function nextAction(status, body) {
  if (status === 402 && body.error?.code === 'AI_USAGE_LIMIT_REACHED') return 'manual-reply'
  if (status === 403 && body.error?.code === 'AI_DISABLED') return 'enable-ai'
  if (status === 403 && body.error?.code === 'FORBIDDEN') return 'fix-key-permissions'
  if (status === 429) return 'wait-with-backoff'
  if (status === 404) return 'check-ai-session'
  if (status >= 400) return 'review-error'
  return 'show-draft'
}

manual-reply の場合は、チームが対応できるよう CRM スレッドを開いたままにし、再試行を繰り返さないでください。enable-ai の場合は、管理者に AI の有効化を案内します。ストアが AI を再び使えるようになったときに再開できるよう、既存のセッション ID を保持します。タイムアウトした AI リクエストは、すでにやり取りを保存している可能性があるため、自動で繰り返さないでください。

リクエスト、レスポンス、エラーの詳しい仕様は Ask AI をご覧ください。

CRM の連携を拡張する

新しいメールスレッドには Public conversations を使用します。既存のスレッドへの返信とは別の操作です。同じリファレンスで、会話に属するアップロードとファイル添付も説明しています。プロフィールの作成、タグやメモリの変更、顧客の削除に必要な 2 つのスコープは Customers をご覧ください。会話や顧客の削除を、通常の更新と同じように自動で再試行しないでください。