Retell AI Webhooks イベント

概要

Retell AI のウェブフックイベントを処理します。コール ライフサイクル、トランスクリプト、関数実行に対応しています。

前提条件

• HTTPS ウェブフック エンドポイント
• ウェブフック URL で設定されたエージェント

手順

ステップ 1: ウェブフック URL を設定

// エージェント設定にウェブフック URL を設定
await retell.agent.update(agentId, {
  webhook_url: 'https://your-app.com/webhooks/retell',
});

ステップ 2: ウェブフック エンドポイント

import express from 'express';

const app = express();
app.post('/webhooks/retell', express.json(), async (req, res) => {
  const { event, call } = req.body;

  switch (event) {
    case 'call_started':
      console.log(`Call started: ${call.call_id} from ${call.from_number}`);
      break;

    case 'call_ended':
      console.log(`Call ended: ${call.call_id}`);
      console.log(`  Duration: ${call.duration_ms}ms`);
      console.log(`  Status: ${call.call_status}`);
      if (call.transcript) {
        await saveTranscript(call.call_id, call.transcript);
      }
      break;

    case 'call_analyzed':
      console.log(`Analysis ready: ${call.call_id}`);
      console.log(`  Summary: ${call.call_analysis?.call_summary}`);
      break;

    default:
      console.log(`Unhandled event: ${event}`);
  }

  res.status(200).json({ received: true });
});

ステップ 3: 会話中の関数呼び出しを処理

// エージェントが関数をトリガーすると、Retell が URL を呼び出します
app.post('/functions/book-appointment', express.json(), async (req, res) => {
  const { patient_name, phone, date, time } = req.body.args;

  // 予約を処理
  const booking = await bookAppointment(patient_name, phone, date, time);

  // エージェントが話すための応答を返す
  res.json({
    result: `Appointment booked for ${patient_name} on ${date} at ${time}. Confirmation number: ${booking.id}`,
  });
});

出力

• コール ライフサイクル イベント用のウェブフック処理
• コール完了時のトランスクリプト保存
• ライブ コール中の関数実行

エラー処理

問題	原因	解決策
ウェブフック イベントがない	URL が設定されていない	エージェントで webhook_url を設定する
関数がタイムアウト	バックエンドが遅い	5 秒以内に応答する
トランスクリプトが不足している	コールが短い	トランスクリプトは 5 秒以上のコールのみ対象

リソース

• Retell AI Documentation
• retell-sdk npm

次のステップ

よくあるエラー: retellai-common-errors