# Instrada i messaggi al tuo agente AI

Bird invia ogni messaggio che ricevi su WhatsApp, SMS, Apple Messages o una casella di posta dell'agente al tuo agente AI. Connetti l'agente una sola volta con i suoi dati e le sue credenziali, e ogni nuovo messaggio lo raggiunge.

Sono supportati due agenti:

- **Claude Managed Agents**: ogni messaggio avvia una sessione di un agente creato nella Claude Console.
- **Grok Bot**: ogni messaggio attiva una delle tue routine Grok Bot.

Bird invia ogni messaggio corrispondente al tuo agente e riprova una consegna non riuscita, quindi un messaggio riprovato può avviare un'altra esecuzione. L'agente riceve l'evento del messaggio JSON, lo stesso payload che riceve un normale [endpoint webhook](/docs/guides/webhooks), e risponde tramite gli strumenti che gli hai fornito, come il [server Bird MCP](/docs/ai/mcp-server).

## Scegli i messaggi a cui risponde il tuo agente

Il tuo agente può rispondere solo ai messaggi in arrivo: `whatsapp.received`, `sms.received`, `amb.received` (Apple Messages) e `email_mailbox.message_received`. Seleziona quelli che l'agente deve gestire. Le conferme di consegna, i cambiamenti di stato e gli altri eventi non vengono inviati a un agente.

## Claude Managed Agents

Per prima cosa, configura il tuo agente nella [Claude Console](https://platform.claude.com/docs/en/managed-agents/quickstart#create-your-first-session): crea l'agente e il suo ambiente, e una [chiave API](https://platform.claude.com/settings/keys) nello stesso spazio di lavoro. Annota l'agent ID e l'environment ID. Le nuove sessioni usano l'ultima versione dell'agente.

Poi collegalo in Bird:

1. [Crea un webhook](https://bird.com/dashboard/w/webhooks/new) e scegli **Claude Managed Agents**.
2. In **Triggers**, seleziona i messaggi a cui Claude deve rispondere.
3. In **Connect**, assegna un nome al webhook e inserisci l'agent ID, l'environment ID e la chiave API.
4. Rivedi il webhook e crealo.

Ogni messaggio avvia una sessione il cui primo messaggio utente è `New Bird event:` seguito dall'evento JSON.

## Grok Bot

Per prima cosa, chiedi a Grok Bot di creare una routine con un trigger webhook. Ti fornirà il webhook URL e la sender key della routine. Per configurare il trigger manualmente, consulta [Cursor's webhook triggers](https://cursor.com/docs/cloud-agent/automations#webhook-triggers).

Poi collegalo in Bird:

1. [Crea un webhook](https://bird.com/dashboard/w/webhooks/new) e scegli **Grok Bot**.
2. In **Triggers**, seleziona i messaggi a cui Grok Bot deve rispondere.
3. In **Connect**, assegna un nome al webhook e incolla il webhook URL e la sender key.
4. Rivedi il webhook e crealo.

Ogni messaggio invia l'evento JSON all'URL webhook della routine, con la sender key come Bearer token, e la routine esegue il prompt salvato.

## Crealo dalla CLI o dalla API

`bird webhooks create --help` elenca ogni connettore con i suoi campi, quali sono segreti, gli eventi accettati e la configurazione preliminare. Passa i campi non segreti con `--field name=value` e ogni segreto da una variabile d'ambiente con `--secret-env name=ENV_VAR`, oppure passalo in pipe con `--secret-stdin name`, così non resta nella cronologia della shell. `--events` include per default tutti gli eventi messaggio accettati dal connettore.

Per Claude, crea una [chiave API](https://platform.claude.com/settings/keys) nello spazio di lavoro in cui gira il tuo agente, poi leggila nell'ambiente senza stamparla a video, così non compare mai in una riga di comando o nella cronologia della shell:

```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
```

La API accetta gli stessi `destination` su [`POST /v1/webhooks`](/docs/api/reference/create-webhook). Ometti `url`: Bird lo costruisce dal connettore. Nessuna risposta include le credenziali.

## Testa la connessione

Subito dopo aver creato il webhook, seleziona **Send test**. In seguito, usa **Send test event** nella pagina del webhook o nelle azioni della riga, oppure chiama [`POST /v1/webhooks/{webhook_id}/test`](/docs/api/reference/test-webhook). Verifica in Claude o Cursor che una sessione o un'esecuzione sia partita. Poi invia un messaggio reale a uno dei tuoi numeri o canali e conferma che l'agente lo gestisca.

## Gestiscilo

- **Ruota una credenziale.** Modifica il webhook e inserisci solo il nuovo valore; un campo lasciato vuoto mantiene il valore memorizzato. Tramite la API, invia la chiave aggiornata in [`PATCH /v1/webhooks/{webhook_id}`](/docs/api/reference/update-webhook) `credentials`. La consegna successiva la usa, tentativi inclusi.
- **Puntalo a un altro agente.** Crea un nuovo webhook. Una modifica non può cambiare piattaforma né impostazioni come l'agent ID o l'URL del webhook.
- **Mettilo in pausa o rimuovilo.** Mettere in pausa un webhook ne interrompe le consegne. Eliminarlo cancella le sue credenziali.
- **Leggere gli errori.** L'elenco dei tentativi di un webhook mostra ogni consegna con lo stato e il corpo della risposta della piattaforma, oppure nulla quando la piattaforma non è stata raggiungibile. Un tentativo fallito prima che Bird inviasse qualcosa, ad esempio una connessione cambiata dopo l'evento, riporta invece un `failure_reason`.

## Passaggi successivi

- [Webhook ed eventi](/docs/guides/webhooks)
- [Server MCP](/docs/ai/mcp-server)
- [Configura il tuo 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)