メインコンテンツまでスキップ

ペイロード仕様

配信形式​

HTTPS POST で JSON ボディが送信されます。Content-Type は application/json。

注記

本ページの構造をそのまま受け取るのは Custom エンドポイントのみです。Slack / Teams / Email は内部で各サービス向けの形式（整形済みテキスト投稿・メール）に変換されます。

サンプル Payload (Custom エンドポイント)​

{
  "message": "[Recho] 発信通話エラー\n━━━━━━━━━━━━━━\ncallId: abc-123\ncallStatus: CALLING\ncallSid: CA94b51...\nclientId: client-1\n━━━━━━━━━━━━━━\nエラー一覧:\n  - [CALL_CONNECTION_FAILED] Failed to initiate or connect the call.\n━━━━━━━━━━━━━━\n時刻: 2026-05-12 10:24:00",
  "data": {
    "callId": "abc-123",
    "callStatus": "CALLING",
    "callSid": "CA94b51...",
    "clientId": "client-1"
  },
  "errors": [
    {
      "code": "CALL_CONNECTION_FAILED",
      "message": "Failed to initiate or connect the call.",
      "timestamp": "2026-05-12T10:23:45.000Z"
    }
  ]
}

TypeScript 型定義​

上のサンプルと同じ構造の型定義です:

type WebhookPayload = {
  message: string; // キー名は contentKey 設定で変更可能（既定は message）
  data: WebhookData;
  errors?: CallError[]; // エラー時のみ
};

type WebhookData = {
  callId: string;
  callStatus: string;
  callSid: string; // 無い場合は空文字
  clientId: string; // 無い場合は空文字
};

type CallError = {
  code: WebhookErrorCode; // エラー分類（/webhooks/error-codes 参照）
  message: string; // 分類ごとに固定の英語メッセージ
  timestamp: string; // ISO 8601 (UTC)
};

type WebhookErrorCode =
  | 'CALL_NOT_PERMITTED'
  | 'CALL_CONNECTION_FAILED'
  | 'CALL_INTERRUPTED'
  | 'CALL_RESULT_PROCESSING_FAILED'
  | 'ANALYZER_FAILED'
  | 'INTERNAL_ERROR'
  | 'UNKNOWN_ERROR';

トップレベルフィールド​

フィールド型用途
messagestring表示用の整形済み本文（人間可読）。改行 (\n) と区切り線入り。ログ表示や通知転送に流すのが想定用途。機械的にパースしないこと。キー名は Webhook 設定の contentKey で変更可能（未設定時は message）
dataWebhookData機械可読な識別情報。プログラム側はここを参照する
errorsArray<CallError> | undefinedエラー時のみ含まれる配列。受信側は errors?.length でエラー判定 → 詳細ログや通知に流用

data フィールド（通話識別情報）​

フィールド型用途
callIdstring通話 ID（一意）。外部システムで通話を識別する主キー。同じ callId の通知は FIFO で配信される（設定ガイド 参照）
callStatusstring通知時点の通話ステータス。値の一覧は 通話ステータス一覧 参照。エラー判定には使えない（errors 配列の有無で行うこと）
callSidstring電話回線プロバイダ側の通話 ID（無い場合は空文字）。プロバイダ側ログとの突合に使う想定
clientIdstringクライアント識別子（任意・無い場合は空文字）。発信時に指定したアプリケーション側 ID をそのまま透過させるためのフィールド
着信通話のステータス別トリガーは callSid / clientId を含みません

INBOUND_CALL_* の data は callId / callStatus の 2 キー（INBOUND_CALL_ERROR はこれに callSid を加えた 3 キー）です。上表の 4 キーが揃うのは発信通話のトリガーと CALL_LOG_CREATED です。

CALL_LOG_CREATED の data には direction が加わります

通話ログ作成トリガー（設定ガイド 参照）はトリガー名に発信・着信の区別を持たないため、上表の 4 キーに加えて direction（OUTBOUND / INBOUND）が入ります。このフィールドを持つのはこのトリガーだけです。

ACW 完了通知の data は構成が異なります

ACW (After Call Work) エージェントの完了通知では、data は以下の 4 キーのみで、上表の callStatus / callSid / clientId は含まれません。

フィールド型用途
callIdstring後処理の対象となった通話 ID
acwAgentIdstring実行された ACW エージェントの ID
acwResultIdstring登録された実行結果の ID。GET /v1/acw-results で本体を取得できる
isErrorstringエージェント実行がエラーだったか（'true' / 'false' の文字列）

なお、ACW エージェントへの起動リクエスト（Self Provided Agent が受け取るリクエスト）も本ページと同じ標準 payload で送信されます。その data は「data フィールド（通話識別情報）」の表のキーに projectId（通話が属するプロジェクトの ID）を加えた構成です。認証（認証方式）と再送（リトライ仕様）の挙動は通常の webhook と同一で、受信側は 2xx を返してください（3xx はエラー扱い）。

errors[] フィールド（エラー詳細）​

エラー発生時のみ含まれる配列で、1 件以上のエラーオブジェクト（code / message / timestamp）が入ります。各フィールドの意味と code に入り得る値は エラーコード一覧 にまとめています。

認証​

認証情報（Bearer トークン / RSA-SHA256 署名）は payload ではなく リクエストヘッダに付与されます。検証方法は 認証方式 を参照してください。