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

bird webhooks create --help lists each connector with its fields, which of them are secret, the events it accepts and the setup to do first. Pass nonsecret fields with --field name=value and each secret from an environment variable with --secret-env name=ENV_VAR, or pipe it with --secret-stdin name, 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 the environment without echoing it, so it never appears in a command line or your shell history:

read -rs ANTHROPIC_API_KEY && export 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 --secret-env api_key=ANTHROPIC_API_KEY

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, or call POST /v1/webhooks/{webhook_id}/test. Check in Claude or Cursor that a session or 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. 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 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.