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

Webhook 設定ガイド

Webhook を設定すると、通話のステータス変更やエラー発生などのイベントを、外部システム（Slack / Microsoft Teams / Email / 独自エンドポイント）にリアルタイムで通知できます。

クイックスタート​

最短手順で疎通確認するには、以下 3 ステップを実施してください。

1. Webhook を受信する最小 Node.js コード​

import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  const { data, errors } = req.body;

  // エラー判定は errors 配列の有無で
  if (Array.isArray(errors) && errors.length > 0) {
    console.error(`callId=${data.callId} has errors`);
  } else {
    console.log(`callId=${data.callId}`);
  }

  // 2xx を返さないと指数バックオフでリトライされます
  res.sendStatus(200);
});

app.listen(3000);

2. ダッシュボードで送信先を登録​

Recho ダッシュボードの「Webhook」ページで、上記エンドポイント URL を Custom タイプとして登録します。

3. 通知トリガーを ON​

「通知トリガー」セクションで、受信したいイベント（例: OUTBOUND_CALL_ERROR）を選択します。

これで疎通確認できる最小構成は完成です。以下、本格運用に必要な内容を続けて読んでください。

設定の流れ（詳細）​

  1. 送信先エンドポイントを登録する ダッシュボードの Webhook ページで「送信先エンドポイント」セクションから「新規作成」を選択し、エンドポイントタイプ（Slack / Teams / Email / Custom）と送信先 URL（またはメールアドレス）を入力します。

  2. 認証方式を選ぶ（Custom の場合） 独自エンドポイントには Bearer トークン認証または RSA 署名検証を設定できます。詳細は 認証方式 を参照してください。

  3. 通知トリガーを有効化する 「通知トリガー」セクションで、どのイベント（発信通話完了、エラー、着信開始など）で Webhook を発火させるかを選択します。

  4. 受信側を実装する 送信される Payload の仕様は ペイロード仕様 を、実装サンプルは 受信サンプル を参照してください。

  5. テスト発火・本番運用 実際に通話を行うか、テストイベントを発火させて疎通を確認してください。

対応エンドポイントタイプ​

種別説明
SlackIncoming Webhook URL を指定すると、整形済みのメッセージが Slack チャンネルに投稿されます
Microsoft TeamsWorkflows / Incoming Webhook URL を指定すると、Teams チャンネルにアダプティブカード形式で投稿されます
Email送信先メールアドレスを指定すると、整形済みの本文がメールで送信されます
Custom任意の HTTPS エンドポイントに JSON を POST します。認証方式（Bearer / RSA 署名）を設定でき、最も柔軟に連携できます

通知の配信先に加えて、通話終了後の後処理（ACW / After Call Work）エージェントを起動するための 種別もあります。

種別説明
Recho AnalyzerRecho 標準の通話分析エージェントを起動します。送信先はプロジェクトから自動解決されるため宛先の指定は不要です（payload の target は null）
Recho EvaluatorRecho 標準の通話評価エージェントを起動します。同じく宛先の指定は不要です（payload の target は null）
Self Provided Agent利用者が自前で用意したエージェントの HTTPS エンドポイントを指定します。エージェントは実行結果を POST /v1/acw-results で登録します

通話ログ作成トリガー (CALL_LOG_CREATED)​

通知トリガーの多くは OUTBOUND_CALL_COMPLETED / INBOUND_CALL_ERROR のように callStatus ごとに分かれています。これに対し CALL_LOG_CREATED は、通話が終了したことを表す特定の callStatus に遷移したときに、発信・着信の区別なく発火します（対象は下表）。

「結果のステータスは問わず、通話が 1 件終わったら起動したい」という用途（特に ACW エージェントの起動）では、ステータス別トリガーを複数並べる代わりにこれ 1 つを有効にすれば済みます。

発火する callStatus​

方向発火する callStatus
OUTBOUNDCOMPLETED / VOICEMAIL_REACHED / ERROR / BUSY / NO_RESPONSE / UNREACHABLE
INBOUNDCOMPLETED / ERROR / CONCURRENCY_LIMIT_EXCEEDED

上表以外のすべての callStatus（発信されずに終了した CANCELED / EXPIRED / MAX_ATTEMPTS_REACHED / HEALTHCHECK_FAILED、通話中の CALLING / CLOSING、および data.callStatus に現れうる内部ステータス）では発火しません。値の一覧は 通話ステータス一覧 を参照してください。

受信側がステータスを判別できることを確認してください

CALL_LOG_CREATED は COMPLETED 以外でも発火します。ACW エージェントなど受信側の実装が data.callStatus を見ずに「通話が正常終了した」前提で処理していると、話し中や到達不可の通知を誤って処理します。受信側が想定するステータスすべてに対応していることを確認したうえで有効化してください。

通知時点で通話ログを参照できるとは限りません

このトリガーは callStatus の遷移で発火します。通話ログの保存そのものを観測しているわけではないため、以下が起こりえます。

  • 通話ログが遅れて保存される: 通知が届いた時点で data.callId の通話ログがまだ保存されていないことがあります（とくに着信通話と、話し中・到達不可で終わった発信通話）。この場合は待てば現れます。
  • 通話ログが最後まで作られない: 架電処理そのものが失敗した発信通話（電話回線プロバイダのエラー、発信権限のエラー、発信前のヘルスチェック失敗など）は COMPLETED / ERROR に終端化されますが、通話は行われていないため通話ログは作られません。着信通話でも、通話中に異常終了してステータスが固着したものが後から ERROR へ終端化された場合は同様です。どちらもいくら待っても現れません。

「遅れて来る」と「絶対に来ない」の両方があるため、受信側が通話ログや文字起こしを読みに行く場合は、リトライに加えて打ち切り条件も用意してください（一定回数・一定時間で諦め、通話ログ無しとして処理する）。

逆に、通話ログは作られたのにこのトリガーがその時点で発火しない経路もあります（着信の受付処理が失敗したときなど、通話自体の callStatus が更新されないケース）。この場合は固着ステータスの検知によって後から ERROR へ終端化されるため、大幅に遅れて発火することがあります。「通話終了から N 分以内に来なければ来ない」と決め打ちすると、忘れた頃の発火で二重処理になります。

いずれにせよ「全通話について必ず 1 通届く」ことを前提にした監査・集計には使えません。

発信・着信の判別​

このトリガーはトリガー名に OUTBOUND_ / INBOUND_ を持たないため、代わりに data.direction に OUTBOUND または INBOUND が入ります。このフィールドを持つのは CALL_LOG_CREATED だけです。

{
  "data": {
    "callId": "abc-123",
    "callStatus": "BUSY",
    "callSid": "CA94b51...",
    "clientId": "client-1",
    "direction": "OUTBOUND"
  }
}

data は発信・着信のどちらでも上記 5 キーで固定です（値が無い場合は空文字）。これは発信のステータス別トリガーのキー集合に direction を足したものと同じです。着信のステータス別トリガーはキー数が少なく（INBOUND_CALL_* は callId / callStatus、INBOUND_CALL_ERROR はこれに callSid を加えた構成）、そちらとは一致しません。詳細は ペイロード仕様 を参照してください。

ステータス別トリガーとの併用​

CALL_LOG_CREATED は既存のステータス別トリガーと並存します。同じ遷移を両方で購読していると、その通話について 2 通届きます（例: 通話が COMPLETED で終わり、OUTBOUND_CALL_COMPLETED と CALL_LOG_CREATED の両方が有効な場合）。重複が不要な場合はどちらか一方だけを有効にしてください。とくに ACW エージェントを起動している場合、エージェントが 2 回実行されます。

data.callId は両方に同じ値が入るため、受信側で 2 通知を突き合わせられます。

配信の挙動​

  • 非同期配信: API 処理本体とは独立して非同期で送信されます。送信失敗が API のレスポンスに影響することはありません。
  • 同一通話内は FIFO 配信: 同一の callId に関するイベントは発火順 (FIFO) で配信されます。内部で FIFO キューを採用しており、ある通話の状態遷移（例: OUTBOUND_CALL_CALLING → OUTBOUND_CALL_COMPLETED）が逆順に届くことはありません。異なる通話間の到達順序は保証されません。
  • 失敗時はリトライ: 受信側が 408 / 429 / 5xx を返したり timeout した場合、指数バックオフで最大 6 回試行します。詳細は リトライ仕様 を参照してください。