Webhook 概要

Webhook は、Wipple CPaaS からお客様のアプリケーションへ送信される HTTP リクエストです。プラットフォームは Webhook を通じて、新規通話の通知、次に何をすべきかの問い合わせ、発生した事象の報告を行います。お客様のアプリケーションは Function の JSON 配列で応答するか、追加の指示が不要な場合は空のボディで応答します。

Webhook の種類

共通プロパティ

通話に関連するすべての Webhook には、お客様自身のレコードと関連付けるために必要な識別子が含まれます。

• call_sid: 通話レグの一意の識別子です。REST API で通話を更新または終了する際に使用します。
• account_sid と application_sid: 通話が属するアカウントとアプリケーションです。
• direction、from、to、caller_name: 誰が誰に発信しているかを示します。
• call_status と sip_status: 通話の現在の状態と最新の SIP ステータスコードです。

アクションフックには Function 固有のプロパティが追加されます。たとえば、gather Function で収集した digits や speech の結果、dial Function 実行後の発信先レグの call_status と duration などです。

HTTP メソッドと URL

フック URL は絶対 URL (https://{yourserver}/menu) でも相対 URL (/menu) でも構いません。相対 URL は、アプリケーションのコールフック URL を基準に解決されます。デフォルトのメソッドは JSON ボディを伴う POST です。フックを GET で設定した場合、同じプロパティが代わりにクエリパラメータとして送信されます。

認証

フックにユーザー名とパスワードを設定すると、Wipple CPaaS はそのフックへのすべてのリクエストに Authorization: Basic <base64(username:password)> ヘッダーを含めます。お客様のアプリケーションはこのヘッダーを検証し、有効な認証情報を持たないリクエストを拒否してください。

応答

• できるだけ速やかに HTTP 200 で応答してください。時間のかかる処理は非同期で実行してください。
• プラットフォームに新しい指示を与えるには、Function の JSON 配列を返します。前回の応答でまだキューに残っている Function は破棄され、置き換えられます。
• 現在のアプリケーションをそのまま継続させるには、空のボディまたは空の配列 [] を返します。
• ステータス専用のフック (コールステータスフック、dtmfHook、eventHook など) では、応答内の Function は無視されます。空のボディを伴う 200 応答で十分です。

WebSocket による代替

HTTP の代わりに、アプリケーション URL を wss:// で始めると、Wipple CPaaS はお客様のサーバーへ WebSocket 接続を開き、その単一の接続上でメッセージとして同じ JSON ペイロードをやり取りします。プロパティ名と Function の定義は同一です。