エラーコード
Visitor API と履歴 API のエラーは、すべて同じ形で返ります。code は数値ではなく文字列です。分岐は必ず code で行い、message では行わないでください。
HTTP ステータスはステータス行にあり、本文には繰り返されません。5xx のエラーでは message は常に決まった一文で、本当の原因はプラットフォームのログに入ります。4xx のエラーでは message は読んでもらうために書かれているので、表示する価値があります。
API チャネル - 受信メッセージの Webhook
Live Chat - Visitor API
いくつかの 404 は、意図的に複数の原因をまとめています。
CONNECTION_NOT_FOUND は 4 つの場合を、ARTIFACT_NOT_FOUND はファイルが無い場合と権限が無い場合の両方をまとめます。どのリソースが存在するかを外から探れないようにするための設計です。Console - チャネル設定
システムの上限
API チャネル - 受信
API チャネル - コールバック
Live Chat
組織全体の枠
本番前チェックリスト
Live Chat チャネル
- チャネルの設定を少なくとも一度保存し、埋め込みコードを手元に持っている。
- コードが閉じ
</body>タグの直前にあり、data-connection-keyが正しく、data-app-originに/chat-widget/のパスが残っている。 - パソコンだけでなく、スマートフォンでも試した。
- モバイルアプリを使う場合: 端末の
localeを渡している。SDK は Console の既定言語を読まないため。 - 自前の画面を作る場合: 自社ドメインが許可リストに入っていて、
credentials: "include"で呼び出していない。
API チャネル
- メッセージの送り先が、Console から取得した Webhook のホスト (
https://console-agents.fpt.ai/webhooks/api) であり、アプリケーションのホストではない。 - 秘密鍵が、ソースコードや git にコミットした設定ファイルではなく、秘密情報の保管先に入っている。
- サーバーの時刻を NTP で同期している。5 分を超えてずれると、すべてのパケットが拒否されます。
- 署名の関数が、再度文字列化したものではなく、本文の生のバイト列を使っている。
- 署名の比較に定数時間の関数を使っている。
messageIdが自社の安定した識別子で、再送しても変わらない。- Webhook がすぐ 200 を返し、処理は非同期にしている。1 回あたり 10 秒しかありません。
- Webhook が
type == "verification"の分岐を扱い、challengeをそのまま返している。 - Console から コールバックをテスト を実行し、合格した。
eventIdによる重複排除を入れている。- コールバックのたびに
conversationIdを保存している。配信の確認も含めて。 - 履歴 API で突き合わせる処理を入れ、失敗したコールバックを埋め合わせている。
- 履歴を読むための専用の API キーを用意し、安全に保管している。
- 429 を
Retry-Afterヘッダーを読んで処理している。 - 503 をバックオフ付きの再送で処理し、拒否されたメッセージとして扱っていない。