Vapi Webhook / Server URL セットアップ

Vapi からのリアルタイムイベント（トランスクリプト、ツール呼び出し、ステータス変更、通話終了レポート）を受け取るようにサーバー URL を設定します。

セットアップ: VAPI_API_KEY が設定されていることを確認してください。必要に応じて setup-api-key スキルを参照してください。

概要

Vapi は「Server URLs」（webhooks）を使用してアプリケーションと通信します。従来の一方向の webhook と異なり、Vapi の Server URL は双方向通信をサポート — サーバーが通話に影響を与えるデータを返信できます。

Server URL を設定する場所

アシスタント上で設定

curl -X PATCH https://api.vapi.ai/assistant/{id} \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serverUrl": "https://your-server.com/vapi/webhook",
    "serverUrlSecret": "your-webhook-secret"
  }'

電話番号上で設定

curl -X PATCH https://api.vapi.ai/phone-number/{id} \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serverUrl": "https://your-server.com/vapi/webhook"
  }'

組織レベルで設定

Vapi ダッシュボードの Settings > Server URL でデフォルトサーバー URL を設定します。

優先順位：Tool server URL > Assistant server URL > Phone Number server URL > Organization server URL。

イベントタイプ

イベント	説明	レスポンスが必要？
assistant-request	動的アシスタント設定のリクエスト	はい — アシスタント設定を返す
tool-calls	アシスタントがツールを呼び出している	はい — ツール結果を返す
status-update	通話ステータスが変更された	いいえ
transcript	リアルタイムトランスクリプト更新	いいえ
end-of-call-report	通話完了とサマリー	いいえ
hang	アシスタントが応答に失敗した	いいえ
speech-update	音声アクティビティ検出	いいえ

Webhook サーバーの例 (Express.js)

import express from "express";
import crypto from "crypto";

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

app.post("/vapi/webhook", (req, res) => {
  const { message } = req.body;

  switch (message.type) {
    case "assistant-request":
      // Dynamically configure the assistant based on the caller
      res.json({
        assistant: {
          name: "Dynamic Assistant",
          firstMessage: `Hello ${message.call.customer?.name || "there"}!`,
          model: {
            provider: "openai",
            model: "gpt-4.1",
            messages: [
              { role: "system", content: "You are a helpful assistant." },
            ],
          },
          voice: { provider: "vapi", voiceId: "Elliot" },
          transcriber: { provider: "deepgram", model: "nova-3", language: "en" },
        },
      });
      break;

    case "tool-calls":
      // Handle tool calls from the assistant
      const results = message.toolCallList.map((toolCall: any) => ({
        toolCallId: toolCall.id,
        result: handleToolCall(toolCall.name, toolCall.arguments),
      }));
      res.json({ results });
      break;

    case "end-of-call-report":
      // Process the call report
      console.log("Call ended:", {
        callId: message.call.id,
        duration: message.durationSeconds,
        cost: message.cost,
        summary: message.summary,
        transcript: message.transcript,
      });
      res.json({});
      break;

    case "status-update":
      console.log("Call status:", message.status);
      res.json({});
      break;

    case "transcript":
      console.log(`[${message.role}]: ${message.transcript}`);
      res.json({});
      break;

    default:
      res.json({});
  }
});

function handleToolCall(name: string, args: any): string {
  // Implement your tool logic here
  return `Result for ${name}`;
}

app.listen(3000, () => console.log("Webhook server running on port 3000"));

Webhook サーバーの例 (Python / Flask)

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/vapi/webhook", methods=["POST"])
def vapi_webhook():
    data = request.json
    message = data.get("message", {})
    msg_type = message.get("type")

    if msg_type == "assistant-request":
        return jsonify({
            "assistant": {
                "name": "Dynamic Assistant",
                "firstMessage": "Hello! How can I help?",
                "model": {
                    "provider": "openai",
                    "model": "gpt-4.1",
                    "messages": [
                        {"role": "system", "content": "You are a helpful assistant."}
                    ],
                },
                "voice": {"provider": "vapi", "voiceId": "Elliot"},
                "transcriber": {"provider": "deepgram", "model": "nova-3", "language": "en"},
            }
        })

    elif msg_type == "tool-calls":
        results = []
        for tool_call in message.get("toolCallList", []):
            results.append({
                "toolCallId": tool_call["id"],
                "result": f"Handled {tool_call['name']}",
            })
        return jsonify({"results": results})

    elif msg_type == "end-of-call-report":
        print(f"Call ended: {message['call']['id']}")
        print(f"Summary: {message.get('summary')}")

    return jsonify({})

if __name__ == "__main__":
    app.run(port=3000)

Webhook 認証

シークレットを使用して webhook の真正性を検証します：

function verifyWebhook(req: express.Request, secret: string): boolean {
  const signature = req.headers["x-vapi-signature"] as string;
  if (!signature || !secret) return false;

  const payload = JSON.stringify(req.body);
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

ローカル開発

Vapi CLI を使用して webhook をローカルサーバーに転送します：

# Install the CLI
curl -sSL https://vapi.ai/install.sh | bash

# Forward events to local server
vapi listen --forward-to localhost:3000/vapi/webhook

または ngrok を使用します：

ngrok http 3000
# Copy the ngrok URL and set it as your server URL

End-of-Call Report フィールド

end-of-call-report イベントには以下が含まれます：

フィールド	説明
call	メタデータを含む完全な通話オブジェクト
transcript	完全な会話トランスクリプト
summary	AI 生成の通話サマリー
recordingUrl	通話録音の URL
durationSeconds	通話時間
cost	合計通話コスト
costBreakdown	コンポーネント別の内訳 (STT, LLM, TTS, transport)
messages	すべての会話メッセージの配列

リファレンス

• Server URL Events — すべてのイベントタイプとペイロードスキーマ
• Vapi Server URL Docs — 公式ドキュメント
• Local Development — ローカルでの webhook テスト

追加リソース

このスキルリポジトリには Vapi documentation MCP server (vapi-docs) が含まれており、AI エージェントが完全な Vapi ナレッジベースにアクセスできます。searchDocs ツールを使用して、このスキルでカバーしていないもの（高度な設定、トラブルシューティング、SDK の詳細など）を検索できます。

自動設定済み: これらのスキルをクローンまたはインストールした場合、MCP サーバーは既に .mcp.json (Claude Code)、.cursor/mcp.json (Cursor)、または .vscode/mcp.json (VS Code Copilot) で設定されています。

手動セットアップ: エージェントが設定を自動検出しない場合は、以下を実行してください：

claude mcp add vapi-docs -- npx -y mcp-remote https://docs.vapi.ai/_mcp/server

サポートされているすべてのエージェント全体の完全なセットアップ手順については、README を参照してください。