mcpField
S
setup-webhook

setup-webhook

github.com/bolna-ai开发366 次安装3 天前更新
代码仓库

关于 setup-webhook

setup-webhook 是用于配置 Bolna HTTP Webhook 的 Skill，可接收通话状态和执行数据。内容涵盖接收端设置、负载处理、重复投递及本地测试。

主要功能

  1. 01为 Agent 配置 Webhook URL
  2. 02接收通话与执行状态更新
  3. 03幂等处理重复负载
  4. 04测试本地接收端

适用场景

  1. 01将执行更新写入数据库
  2. 02触发 CRM 或支持工作流
  3. 03补取未收到的投递数据

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/bolna-ai/skills --skill setup-webhook

安装后在 Claude Code 中输入/setup-webhook确认已加载。

附带文件scripts/webhook_receiver.py

详细介绍

设置 Bolna Webhook

Bolna 会发送什么

通话状态和执行数据发生变化时，Bolna 会向已配置的 Webhook URL 发送 HTTP POST 请求。请将 Webhook 负载视为执行对象；如需核对漏发或重复投递的数据，请对同一执行 ID 使用 get-executions。

配置位置

  • 控制面板：Agent 的 Analytics 选项卡中的“将所有执行数据推送到 Webhook”。
  • API：创建或修改 Agent 时设置 agent_config.webhook_url。

API 修改

curl --request PATCH \
  --url "https://api.bolna.ai/v2/agent/$AGENT_ID" \
  --header "Authorization: Bearer $BOLNA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "agent_config": {
      "webhook_url": "https://example.com/bolna/webhook"
    }
  }'

接收端要求

  • 生产环境中使用公开的 HTTPS URL。
  • 接受 POST JSON。
  • 快速返回 2xx。
  • 按 execution_id 或 id 以幂等方式存储。
  • 触发不可逆的下游操作前，先验证负载格式。
  • 如果配置了防火墙，在添加允许列表之前，请查阅 Bolna 的最新文档，确认 Webhook 的源 IP。

本地测试接收端

python3 setup-webhook/scripts/webhook_receiver.py --port 8080

使用 ngrok 或 Cloudflare Tunnel 等工具建立隧道，然后在 Bolna 中配置公开的 HTTPS URL。

最简负载处理模式

  1. 解析 JSON。
  2. 提取执行 ID、状态、Agent ID、电话号码、转录文本、录音 URL 和提取的数据。
  3. 按执行 ID 在数据库中执行插入或更新。
  4. 仅在相关终态（通常为 completed、failed、no-answer、busy 或 error）后触发自动化。
  5. 如果负载不完整，请调用 GET /executions/{execution_id}。

常见自动化

  • 将摘要和录音发送到 CRM。
  • 根据提取的数据更新潜在客户状态。
  • 转接失败后创建支持工单。
  • 通过 Make、Zapier、n8n 或自定义代码发送 WhatsApp、SMS 或电子邮件。
  • 根据 queued、ringing、in-progress 和 completed 构建实时仪表板卡片。

要加入允许列表的源 IP

Bolna 从单个源 IP 投递 Webhook：

13.203.39.153

将此 IP 添加到服务器的防火墙允许列表。如果端点敏感，请拒绝其他所有请求。

负载格式

Webhook 请求正文与 GET /executions/{execution_id} 的响应完全相同。完整字段列表请参阅 https://raw.githubusercontent.com/bolna-ai/skills/main/references/execution-payload.md，状态触发顺序请参阅 https://raw.githubusercontent.com/bolna-ai/skills/main/references/call-statuses.md。

幂等性

同一执行可能随着 status 变化（scheduled → queued → in-progress → completed）多次触发 Webhook 投递。请按 (execution_id, status) 去重，切勿仅按 execution_id 去重，否则会丢弃后续更新。

另请参阅

  • https://raw.githubusercontent.com/bolna-ai/skills/main/references/execution-payload.md — 负载中的所有字段。
  • https://raw.githubusercontent.com/bolna-ai/skills/main/references/call-statuses.md — 状态顺序和终态筛选条件。
  • get-executions — 拉取 Webhook 投递失败的执行记录的历史数据。
  • debug-bolna-calls — 诊断漏发问题。

评论

支持 Markdown