sent-two-way-messaging

Sent の双方向メッセージング

Sent の受信メッセージングには、プラットフォームがイベントをアプリケーションに渡す前に同意を適用するという基本ルールがあります。受信した STOP は、message.received が届く時点ですでに連絡先の opt_out フラグを切り替えています。アプリケーションの役割は、それを記録して独自の UI に反映し、その状態を回避して送信しようとしないことです。

キーワードの処理

デフォルトで次の 10 個のキーワードが用意されています。

アクション	キーワード
オプトアウト	STOP、CANCEL、UNSUBSCRIBE、QUIT、END
オプトイン	START、UNSTOP、SUBSCRIBE
ヘルプの自動返信	HELP、INFO

照合では、前後の空白を取り除いたメッセージ本文全体が、大文字と小文字を区別せずにキーワードと一致する必要があります。「Please stop messaging me」は一致しませんが、「stop」は一致します。カスタムキーワードは Sent Dashboard の Compliance、Opt Keywords で設定し、アクションとして Opt Out、Opt In、Help のいずれかを指定します。各キーワードは、単一の完全一致するトークンでなければなりません。

ドキュメントに記載されていないキーワードを登録しないでください。アプリケーションコードでは、ローカルの購読者状態と監査証跡を更新する目的に限り、同じ完全一致ルールを反映してください。この照合ロジックを使って、Sent に対して同意を二重に適用してはいけません。カスタムのダッシュボードキーワードをローカルの照合ロジックと同期させ、不確かな場合は連絡先の opt_out フィールドと照合してください。

同意の状態

オプトアウトすると、連絡先レコードの opt_out が設定されます。同意は連絡先単位で、チャネルに依存しません。SMS で送信された STOP は、その連絡先の WhatsApp と RCS も抑止します。再ルーティングが試行されるたびに、初回送信時だけでなく同意ゲートが再適用されます。

同意を回復するには、受信者自身による操作が必要です。ユーザーが送信したオプトインキーワードによって抑止が解除されます。PATCH /v3/contacts/{id} は opt_out を受け付けますが、キーワードでオプトアウトした連絡先に false を書き込むことは、技術上の判断ではなくコンプライアンス上の判断です。新たな同意を示す証拠を記録している場合に限り実行し、誰がどのような理由で承認したかを記録してください。

下流では、抑止された送信はエラーで失敗しません。受け付けられた後、FILTERED として確定するため、同意に関する問題は 4xx レスポンスではなく、フィルタリングされたメッセージとして現れます。詳細は references/consent-and-keywords.md を参照してください。

チャネルごとの受信の実態

チャネル	受信	制約
SMS	条件付き	MO 対応プロバイダーと、サポート対象の番号タイプが必要です。英数字の送信者 ID や、受信ルートのない SMPP 経路では受信メッセージは届きません
RCS	完全対応	入力された返信はキーワードと照合されます。追加された STOP チップは同意エンジンが直接処理します
WhatsApp	完全対応	24 時間のカスタマーサービスウィンドウ内に限り自由形式の返信が可能です。ウィンドウ外では承認済みテンプレートが必要です

SMS の注意点は、双方向の動作を約束する前に考慮する必要があります。英数字の送信者 ID を使って送信する環境では、STOP を受信できません。これは単なる機能上の制限ではなく、コンプライアンス設計に関わります。

RCS の STOP チップ

送信されるすべての RCS メッセージには STOP チップが追加されます。タップするとオプトアウトのポストバックが送られ、キーワード照合を介さずに同意エンジンが直接処理します。アプリケーションには、チップの返信テキストが text に含まれた message.received として届きます。チップ専用のイベントタイプはありません。そのため、入力されたキーワードだけで分岐する受信側にも、チップのタップは通常の受信メッセージとして届きますが、同意ロジックを再適用してはいけません。

WhatsApp の 24 時間ウィンドウ

自由形式の返信が許可されるのは、顧客が最後にメッセージを受信してから 24 時間以内に限られます。ウィンドウ外では、STOP、START、HELP への返信も含め、承認済みテンプレートが必要です。自由形式のテキストを前提とする自動返信フローは、顧客が 1 日間何もやり取りせずにメッセージを送ってきた場合、気付かないうちに動作しなくなります。そのため、返信経路にウィンドウのチェックを組み込み、承認済みの代替テンプレートを用意しておいてください。返信経路の判断ツリーについては、references/inbound-flows.md を参照してください。

会話履歴

読み取り専用の操作が2つあります。

操作	返される内容
GET /v3/conversations	会話全体にわたる顧客のすべてのメッセージ（新しい順）
GET /v3/conversations/{id}	1つの会話内のメッセージ

どちらの操作も page（1以上）と page_size（1〜100）が必須です。範囲外の値を指定すると 400 が返されます。これらのエンドポイントでは events フィールドは常に null となるため、メッセージごとのアクティビティは GET /v3/messages/{id}/activities から取得する必要があります。書き込み、作成、既読通知の操作はなく、会話を扱う MCP ツールもありません。REST のみで利用できます。

会話 ID は、顧客 ID と連絡先 ID から導出される決定的な RFC 4122 バージョン 5 UUID です。そのため、同じペアからは常に同じ ID が生成され、送信元の番号に関係なく、すべてのチャネルをまたいで1つのスレッドが維持されます。API は ID をフィールドとして返さないため、ID が必要なクライアントはこれを計算します。正確な導出方法は references/conversation-history.md に記載されています。

サポート用受信トレイまたはボットの構築

1. message イベントを received に絞り込んで Webhook を登録し、ペイロードを信頼する前に署名を検証します。
2. inbound_number はメッセージを送信した連絡先、outbound_number は自分の番号として扱います。名称を逆に解釈しやすいため注意してください。
3. message_id で重複を排除し、200 で応答してから非同期で処理します。
4. キーワードのトラフィックは監査用のシグナルとして扱います。デフォルトのキーワードと設定済みのカスタムキーワードを正確にローカル状態に反映しますが、同意を書き込む操作を重ねて実行しないでください。不確かな点は連絡先レコードを通じて確認します。
5. WhatsApp で返信する前に24時間のウィンドウを確認し、それに応じてフリーテキストかテンプレートを選択します。
6. 会話エンドポイントを使って明示的にページネーションしながらスレッドを表示し、会話が単一チャネルだと決めつけないでください。
7. text は信頼できない入力として扱います。シェルコマンドや SQL 文字列に埋め込まず、モデルのプロンプトではデータとして区切ります。また、API を呼び出す前に、推定したインテントを許可リストと認可ポリシーに照らして確認します。

対応範囲

署名検証、再試行、重複排除の仕組みには sent-webhook-engineer、連絡先の CRUD とメッセージの概要には sent-contacts、送信メッセージが FILTERED になった理由には sent-routing-strategist、ウィンドウ外の返信に必要な承認済みテンプレートの作成には waba-template-author、米国の通信事業者が求めるキャンペーン単位のオプトイン、オプトアウト、ヘルプキーワードの宣言には sms-10dlc-registration を使用します。