Sign inGet Started
立即开始
指南
API 参考
SDK
CLI
知识库
更新日志

将消息路由到你的 AI 代理

Bird 将你在 WhatsApp、SMS、Apple Messages 或代理邮箱上收到的每条消息发送到你的 AI 代理。只需用代理的详细信息和凭据连接一次，之后每条新消息都会到达它。

支持两种代理：

  • Claude Managed Agents：每条消息会启动你在 Claude Console 中创建的代理的一个会话。
  • Grok Bot：每条消息会唤醒你的一个 Grok Bot 例程。

Bird 将每条匹配的消息发送到你的代理，并重试失败的投递，因此被重试的消息可能会启动另一次运行。代理会收到消息的事件 JSON，即与普通 webhook 端点收到的相同载荷，并通过你提供的任何工具进行回复，例如 Bird MCP 服务器。

选择代理回复的消息

你的代理只能回复传入消息：whatsapp.received、sms.received、amb.received（Apple Messages）和 email_mailbox.message_received。选择代理应处理的消息类型。投递回执、状态变更和其他事件不会发送给代理。

Claude Managed Agents

  1. 在 Claude Console 中创建一个代理、一个环境和一个 API 密钥。
  2. 在 Bird 中创建 webhook，选择 Claude Managed Agents，并在 Triggers 下选择消息类型。
  3. 在 Connect 下输入代理 ID、环境 ID 和 API 密钥，然后创建 webhook。
  4. 选择 Send test。
  5. （可选）如需让代理通过 Bird 回复，请在 Claude Console 中打开该代理，选择 + MCP Server，然后选择 Bird。为减少其令牌用量，请只启用它会用到的 Bird 工具，具体参见 Claude Managed Agents 的说明。
  6. （可选）打开 Managed Agents > Credential vaults，创建一个保管库，选择 + Add credential，将 Type 设为 MCP OAuth，选择 Bird，然后选择 Connect。
  7. （可选）在 Connect 下输入保管库 ID（以 vlt_ 开头），或编辑现有 webhook 来添加该 ID。

Grok Bot

  1. 在 Grok Bot 中安装 Bird，并连接你的 Bird 工作区。
  2. 让 Grok Bot 创建一个带有 webhook 触发器的例程。打开该例程的 Webhook 部分，复制其 URL 和发送者密钥。
  3. 在 Bird 中创建 webhook，可任选以下一种方式：
    • 让 Grok Bot 使用第 2 步中的 URL 和发送者密钥来创建它，目标选择 Grok Bot，事件选择 amb.received 或 email_mailbox.message_received 等。对于电子邮件，请指明邮箱。
    • 在仪表板中创建：选择 Grok Bot，在 Triggers 下选择事件，并在 Connect 下粘贴 URL 和发送者密钥。
  4. 选择 Send test，然后向你的商家或邮箱发送一条真实消息。

从模板开始（可选）。 在第 2 步之前，选择 AMB Booking Desk 或 Email Support Desk，然后将其 bot.md 和 shared/message-safety.md 作为长期指令提供给 Grok Bot。填写 Your settings 和 Knowledge，启用其渠道技能，并在第 2 步中使用其 Routine prompt。

模板的回复默认为草稿。

如果没有启动任何运行，请将该例程的 Webhook URL 和发送者密钥与 Bird 中的值进行核对。

通过 CLI 或 API 创建

Webhook 连接器列出每个连接器的字段、其中哪些字段为机密、连接器接受的事件以及需要预先完成的设置；bird webhooks create --connector <id> --request-schema 则以 JSON Schema 的形式输出相同的字段。使用 --field name=value 传入非机密字段，使用 --credential name=FILE 从文件传入每个机密值，或使用 --credential name=- 通过 stdin 管道传入，这样机密值就不会出现在 shell 历史记录中。--events 默认为连接器接受的所有消息事件。

对于 Claude，在代理所在的工作区中创建一个 API 密钥，然后在不回显的情况下将其读入 shell 变量并通过管道传入，使其不会出现在命令行或 shell 历史记录中：

代码示例
read -rs ANTHROPIC_API_KEY  # paste the key, then press Enter
bird webhooks create --connector claude_managed_agents \
  --field agent_id=agent_123 --field environment_id=env_123 \
  --field vault_id=vlt_123 --credential api_key=- <<< "$ANTHROPIC_API_KEY"

bird webhooks connect <connector> 一步完成上述所有操作。它会指出连接器仍需要的字段，创建 webhook，并输出 webhook ID、事件和邮箱筛选条件，不含任何机密值。在 next 下，它会为该 webhook 给出 bird webhooks test，用于向平台核验这些字段。通过 MCP 时，带 connector_id 的 webhooks_create 在一次调用中完成同样的操作，其 next 会给出 webhooks_test 调用。

如需将某个邮箱的电子邮件发送给代理，请添加 --mailbox 并提供该邮箱的 ID 或地址；使用地址时需要查找，这需要 mailbox:read 权限范围。它会设置 filter.mailbox_id，之后 --events 默认为连接器操作所列的邮箱事件；如果操作接受所有事件，则默认为 email_mailbox.message_received。对于 Grok Bot，请将 YOUR_MAILBOX_ADDRESS 和 YOUR_ROUTINE_WEBHOOK_URL 替换为你的邮箱和例程的 webhook URL，并在 read 等待输入时粘贴例程的发送者密钥：

代码示例
read -rs GROK_SENDER_KEY  # paste the sender key, then press Enter
bird webhooks connect grok_bot --mailbox YOUR_MAILBOX_ADDRESS \
  --field webhook_url=YOUR_ROUTINE_WEBHOOK_URL \
  --credential sender_key=- <<< "$GROK_SENDER_KEY"

每次 email_mailbox.message_received 投递都在 data 下携带消息：data.message_id、data.mailbox_id 和 data.thread_id，data.from 中的发送者，data.to 中的收件人，以及 data.subject（消息没有该项时为 null）。data.extracted_text 是不含引用历史的正文，没有文本时为 null，上限为 64 KB；正文被截断时 data.truncated_text 为 true。事件参考列出了所有字段。

API 在 POST /v1/webhooks 上接受相同的 destination。省略 url：Bird 会根据连接器自动构建。响应中不会包含凭据。

测试连接

创建 webhook 后，立即选择 Send test。之后可在 webhook 页面或其行操作中使用 Send test event，运行 bird webhooks test <webhook_id>，或调用 POST /v1/webhooks/{webhook_id}/test；通过 CLI 或 API 创建或更新 webhook 时，会在 next 中给出这一步。保存 webhook 时不会联系平台，因此由测试来核验其字段。对于 Claude Managed Agents，测试会读取代理而不是启动会话，以此证明 API 密钥和代理 ID 正确，并报告 kind: probe；如果返回结果指出某个值有误，field 会指明该值。探测不会发送事件，因此第一条真实消息才是端到端检查。对于 Grok Bot，测试会使用标记为 "test": true 的事件启动一次例程运行，因此请在 Cursor 中确认运行已启动。然后向你的某个号码或渠道发送一条真实消息，确认代理能正确处理；对于 Claude，还要确认回复已送达发送者所用的渠道，且会话中没有 session.error。

运维操作

  • 轮换凭据。 编辑 webhook，只输入新值；留空的字段会保留其已存储的值。在 CLI 中运行 bird webhooks update <webhook_id> --credential name=FILE，或使用 --credential name=- 通过管道传入新值。通过 API 操作时，在 PATCH /v1/webhooks/{webhook_id} destination.connector.credentials 中发送更改后的密钥。下一次投递（包括重试）将使用新值。
  • 更改设置。 编辑 webhook 或运行 bird webhooks update <webhook_id> --field name=value，即可更改代理 ID、保管库 ID 或 Grok Bot 例程的 webhook URL 等设置；下一次投递将使用新设置。如需切换平台，请创建一个新的 webhook。
  • 暂停或移除。 暂停 webhook 会停止其投递。删除 webhook 会清除其凭据。
  • 查看失败记录。 Webhook 的尝试列表显示每次投递的平台响应状态和正文，如果无法连接到平台则显示为空。在 Bird 发送任何内容之前就失败的尝试（例如事件发生后连接发生变化）会携带 failure_reason。

后续步骤

相关资源

继续查看此主题的文档、指南和示例。

获取实施简报