Route messages to your AI agent

Bird sends each message you receive on WhatsApp, SMS, Apple Messages or an agent mailbox to your AI agent. Connect the agent once with its details and credentials, and every new message reaches it.

Two agents are supported:

• Claude Managed Agents: each message starts a session of an agent you created in the Claude Console.
• Grok Bot: each message wakes one of your Grok Bot routines.

Bird sends each matching message to your agent and retries a delivery that fails, so a retried message can start another run. The agent receives the message's event JSON, the same payload a plain webhook endpoint receives, and replies through whatever tools you gave it, such as the Bird MCP server.

Choose the messages your agent answers

Your agent can answer incoming messages only: whatsapp.received, sms.received, amb.received (Apple Messages) and email_mailbox.message_received. Pick the ones the agent should handle. Delivery receipts, status changes and other events are not sent to an agent.

Claude Managed Agents

1. In the Claude Console, create an agent, an environment and an API key.
2. In Bird, create a webhook, choose Claude Managed Agents and select the messages under Triggers.
3. Under Connect, enter the agent ID, environment ID and API key, then create the webhook.
4. Select Send test.
5. (Optional) To let the agent reply through Bird, open the agent in the Claude Console, select + MCP Server and pick Bird. To keep its token use down, enable only the Bird tools it uses, as Claude Managed Agents describes.
6. (Optional) Open Managed Agents > Credential vaults, create a vault, select + Add credential, set Type to MCP OAuth, pick Bird and select Connect.
7. (Optional) Enter the vault ID (it starts with vlt_) under Connect, or edit an existing webhook to add it.

Grok Bot

1. Install Bird in Grok Bot and connect your Bird workspace.
2. Ask Grok Bot to create a routine with a webhook trigger. Open the routine’s Webhook section and copy its URL and sender key.
3. Create the webhook in Bird, either way:
   • Ask Grok Bot to create it with a Grok Bot destination for an event such as amb.received or email_mailbox.message_received, using the URL and sender key from step 2. For email, name the mailbox.
   • Create it in the dashboard: choose Grok Bot, select the event under Triggers and paste the URL and sender key under Connect.
4. Select Send test, then send a real message to your business or mailbox.

Start from a template (optional). Before step 2, pick AMB Booking Desk or Email Support Desk, then give Grok Bot its bot.md and shared/message-safety.md as lasting instructions. Fill in Your settings and Knowledge, enable its channel skill and use its Routine prompt for step 2.

Template replies default to drafts.

If no run starts, check the routine’s Webhook URL and sender key against the values in Bird.

Create it from the CLI or API

Webhook connectors lists each connector's fields, which of them are secret, the events it accepts and the setup to do first, and bird webhooks create --connector <id> --request-schema prints the same fields as a JSON Schema. Pass nonsecret fields with --field name=value and each secret with --credential name=FILE from a file, or --credential name=- piped on stdin, so it stays out of your shell history. --events defaults to every message event the connector accepts.

For Claude, create an API key in the workspace your agent runs in, then read it into a shell variable without echoing it and pipe it in, so it never appears in a command line or your shell history:

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> does all of this in one step. It names any field the connector still needs, creates the webhook, and prints the webhook ID, events and mailbox filter, with no secret. Under next it names bird webhooks test for the webhook, which checks the fields with the platform. Through MCP, webhooks_create with connector_id does the same in one call, and its next names the webhooks_test call.

To send one mailbox's email to the agent, add --mailbox with the mailbox's ID or address; an address is looked up, which needs the mailbox:read scope. It sets filter.mailbox_id, and --events then defaults to the mailbox events the connector's action lists, or to email_mailbox.message_received for an action that accepts every event. For Grok Bot, replace YOUR_MAILBOX_ADDRESS and YOUR_ROUTINE_WEBHOOK_URL with your mailbox and the routine's webhook URL, and paste the routine's sender key when read waits for it:

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"

Each email_mailbox.message_received delivery carries the message under data: data.message_id, data.mailbox_id and data.thread_id, the sender in data.from, the recipients in data.to, and data.subject, which is null when the message had none. data.extracted_text is the body without quoted history, null when there is no text, and capped at 64 KB; data.truncated_text is true when it was cut. The event reference lists every field.

The API takes the same destination on POST /v1/webhooks. Leave url out: Bird builds it from the connector. No response includes the credentials.

Test the connection

Right after creating the webhook, select Send test. Later, use Send test event on the webhook's page or in its row actions, run bird webhooks test <webhook_id>, or call POST /v1/webhooks/{webhook_id}/test; a create or update from the CLI or the API names this step in next. Saving the webhook does not contact the platform, so the test is what checks its fields. For Claude Managed Agents the test reads the agent instead of starting a session, which proves the API key and the agent ID, and reports kind: probe; when the answer identifies a wrong value, field names it. A probe sends no event, so the first real message is the end-to-end check. For Grok Bot the test starts a routine run with an event marked "test": true, so check in Cursor that a run started. Then send a real message to one of your numbers or channels and confirm the agent handles it; for Claude, confirm the reply arrives on the sender's channel and the session shows no session.error.

Operate it

• Rotate a credential. Edit the webhook and enter only the new value; a field you leave blank keeps its stored value. From the CLI, run bird webhooks update <webhook_id> --credential name=FILE, or pipe the value with --credential name=-. Through the API, send the changed key in PATCH /v1/webhooks/{webhook_id} destination.connector.credentials. The next delivery uses it, retries included.
• Change its settings. Edit the webhook, or run bird webhooks update <webhook_id> --field name=value, to change a setting such as the agent ID, the vault ID or a Grok Bot routine's webhook URL; the next delivery uses it. To switch platforms, create a new webhook.
• Pause or remove it. Pausing a webhook stops its deliveries. Deleting it erases its credentials.
• Read failures. A webhook's attempts list each delivery with the platform's response status and body, or none when the platform could not be reached. An attempt that failed before Bird sent anything, such as a connection changed after the event, carries a failure_reason instead.

Next steps

• MCP Events, for an MCP client that subscribes to these events itself
• Webhooks & events
• MCP server
• Set up your coding agent
• Superagent: score inbound email, SMS and WhatsApp messages before your agent acts on them.