# 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](/docs/guides/webhooks) receives, and replies through whatever tools you gave it, such as the [Bird MCP server](/docs/ai/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

First, set up your agent in the [Claude Console](https://platform.claude.com/docs/en/managed-agents/quickstart#create-your-first-session): create the agent and its environment, and an [API key](https://platform.claude.com/settings/keys) in the same workspace. Note the agent ID and the environment ID. New sessions use the agent's latest version.

Then connect it in Bird:

1. [Create a webhook](https://bird.com/dashboard/w/webhooks/new) and choose **Claude Managed Agents**.
2. Under **Triggers**, select the messages Claude should answer.
3. Under **Connect**, name the webhook and enter the agent ID, the environment ID and the API key.
4. Review the webhook and create it.

Each message starts a session whose first user message is `New Bird event:` followed by the event JSON.

## Grok Bot

First, ask Grok Bot to create a routine with a webhook trigger. It gives you the routine's webhook URL and sender key. To set the trigger up by hand instead, see [Cursor's webhook triggers](https://cursor.com/docs/cloud-agent/automations#webhook-triggers).

Then connect it in Bird:

1. [Create a webhook](https://bird.com/dashboard/w/webhooks/new) and choose **Grok Bot**.
2. Under **Triggers**, select the messages Grok Bot should answer.
3. Under **Connect**, name the webhook and paste the webhook URL and the sender key.
4. Review the webhook and create it.

Each message posts the event JSON to the routine's webhook URL, with the sender key as the Bearer token, and the routine runs its saved prompt.

## 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](https://platform.claude.com/settings/keys) 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:

```bash
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 \
  --secret-env api_key=ANTHROPIC_API_KEY
```

The API takes the same `destination` on [`POST /v1/webhooks`](/docs/api/reference/create-webhook). 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`](/docs/api/reference/test-webhook). 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.

## 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}`](/docs/api/reference/update-webhook) `credentials`. The next delivery uses it, retries included.
- **Point it at another agent.** Create a new webhook. An edit cannot switch platforms or change settings such as the agent ID or the webhook URL.
- **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

- [Webhooks & events](/docs/guides/webhooks)
- [MCP server](/docs/ai/mcp-server)
- [Set up your coding agent](/docs/ai/set-up-your-agent)

## Related resources

- [Setting up your coding agent](/learn/basics/setting-up-your-coding-agent) (video)
- [What is an MCP server, and how does an agent use one to send messages?](/explained/platform/what-is-an-mcp-server-and-how-does-an-agent-send-messages) (answer)
- [Coding agents](/ai) (product)
- [Build with AI agents](/learn/paths/agents) (course)

[Get an implementation brief](/learn/workspace?topic=agents)