通常のワークスペースで WhatsApp 発信の Webhook を受け取る
UnifyPort の通常ワークスペースで WhatsApp の1対1発信を準備できます。Webhook エンドポイントの購読が ["*"] だけの場合、メッセージは届いても発信のコールバックが届かないことがあります。接続と終了の両方を受け取るには、call.answered と call.ended を明示的に購読します。
通話作成のリファレンスは、UnifyPort の非公式インターフェースを通じて人が開始する音声・ビデオ発信を対象としています。call.incoming は将来の着信機能用に予約されています。
1. ワークスペースの購読ルールを確認する
| ワークスペース | 購読方法 | 発信イベント |
|---|---|---|
| 通常 | ["*"]、[]、またはリストを省略 | 通常イベントのみ |
| 通常 | subscribed_events にイベント名を明示 | 列挙した発信イベントを受信 |
| ベータ | 明示リスト、ワイルドカード、空リスト、または省略 | 一致する発信イベントを受信 |
配信条件を満たすエンドポイントには、明示した名前に対応するイベントが届きます。通常ワークスペースでは、* と2つの発信イベント名を併記すると、通常イベントのワイルドカード購読を維持できます。通常ワークスペースで予約済みの call.incoming を明示すると、403 beta_feature_not_enabled(41002)が返ります。
2. 更新前にエンドポイント設定を取得する
Webhook エンドポイントの取得で、送信先 URL、状態、現在の購読と再試行設定を確認します。ワークスペースのエンドポイントか、特定のメッセージングアカウントに紐付くものかを確認します。更新時には既存のアカウントとの紐付けが保持されます。
Webhook エンドポイントの更新は設定を置き換えます。送信前に更新後の設定一式を用意し、現在の URL、状態、再試行設定を保持します。署名が有効な場合は、自分の安全な設定ストアから既存のシークレットを取得します。取得レスポンスでは signing_enabled を確認でき、シークレットはアプリ側で管理します。signing_secret を省略するか空にすると署名が無効になります。再試行設定を省略すると、初回配信後に3回再試行する既定値に戻ります。
3. メッセージ購読を維持しながら発信イベントを追加する
現在ワイルドカードを使うエンドポイントでは、次の本文を PATCH /v1/webhook-endpoints/{endpoint_id} に送信します。例は、有効かつ署名付きで、再試行回数が3回のエンドポイントを想定しています。実際の URL、状態、シークレット、再試行設定に置き換えてください。API キーと署名用シークレットはサーバーで管理します。
{
"url": "https://support.example.com/webhook",
"status": "active",
"subscribed_events": ["*", "call.answered", "call.ended"],
"signing_secret": "<EXISTING_WEBHOOK_SIGNING_SECRET>",
"retry_policy": { "max_attempts": 3 }
}
明示リストを使う場合は、既存の名前をコピーして発信イベントを2つ追加します。現在のリストが message.received と message.read だけの場合、次の配列を更新本文全体の subscribed_events に指定します。
["message.received", "message.read", "call.answered", "call.ended"]
更新後に再度取得し、URL、状態、購読、署名の有効状態、再試行設定を確認します。受信側が通話イベント2種類と既存のメッセージイベントを処理できることも確認してください。
4. 新しい発信を1回行って配信を確認する
- 同じ認証済み WhatsApp メッセージングアカウントからテスト会話を選びます。
POST /v1/callsで通話を準備し、返されたcall_idをアプリのタスクに紐付けて保存します。 201のstate: preparingはリンクの準備完了を示します。担当者はexpires_atより前に非公開のjoin_urlを開き、Start call を押します。- テスト通話が接続され、終了したら、接続イベントと終了イベントを確認します。イベントの
account_idとdata.call.idを保存済みの記録と照合します。 - 既存のフローからテストメッセージを送信し、想定するイベントが受信側に届くことを確認します。
署名付きエンドポイントでは、配信と署名検証のガイドに従って生のリクエスト本文を検証します。イベント id で重複を排除し、順序が逆転しても処理できるようにします。遅れて届いた接続イベントは証拠として保存し、通話記録は終了済みのままにします。message.* の通話記録は別の用途です。
5. 届かない原因を調べ、設定を戻せるようにする
コールバックが届かない場合は、正確なイベント名、エンドポイントの対象範囲と有効状態を確認し、受信ログ、HTTP レスポンス、アプリの保存状況を調べます。2xx は配信への応答です。永続化とタスクとの紐付けは個別に確認します。配信、再試行、デッドレターの再処理では、その時点の資格と購読を使います。
元のエンドポイント設定と署名用シークレットへの参照を保存します。元に戻す場合は、以前の設定一式を送信し、メッセージ配信を再確認します。支援が必要な場合は、エンドポイント ID、アカウント ID、通話 ID、UTC 時刻と機密情報を除いた受信結果をテクニカルサポートに伝えてください。API キー、シークレット、通話リンクの全文は非公開にします。
メッセージ連携を安定したプロダクトパイプラインへ。
まずは 1 つの API で送信を始め、標準イベントですべての inbound メッセージを業務システムへ戻しましょう。