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, e risponde tramite gli strumenti che gli hai fornito, come il server Bird MCP.

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

1. Nella Claude Console, crea un agente, un ambiente e una chiave API.
2. In Bird, crea un webhook, scegli Claude Managed Agents e seleziona i messaggi in Triggers.
3. In Connect, inserisci l'agent ID, l'environment ID e la chiave API, poi crea il webhook.
4. Seleziona Send test.
5. (Facoltativo) Per consentire all'agente di rispondere tramite Bird, apri l'agente nella Claude Console, seleziona + MCP Server e scegli Bird. Per contenere il consumo di token, abilita solo gli strumenti Bird che l'agente usa, come descritto in Claude Managed Agents.
6. (Facoltativo) Apri Managed Agents > Credential vaults, crea un vault, seleziona + Add credential, imposta Type su MCP OAuth, scegli Bird e seleziona Connect.
7. (Facoltativo) Inserisci il vault ID (inizia con vlt_) in Connect, oppure modifica un webhook esistente per aggiungerlo.

Grok Bot

1. Installa Bird in Grok Bot e collega il tuo spazio di lavoro Bird.
2. Chiedi a Grok Bot di creare una routine con un trigger webhook. Apri la sezione Webhook della routine e copia il suo URL e la sender key.
3. Crea il webhook in Bird in uno dei due modi:
   • Chiedi a Grok Bot di crearlo con una destinazione Grok Bot per un evento come amb.received o email_mailbox.message_received, usando l'URL e la sender key del passaggio 2. Per le email, indica la casella di posta.
   • Crealo nella dashboard: scegli Grok Bot, seleziona l'evento in Triggers e incolla l'URL e la sender key in Connect.
4. Seleziona Send test, poi invia un messaggio reale alla tua attività o alla tua casella di posta.

Parti da un template (facoltativo). Prima del passaggio 2, scegli AMB Booking Desk o Email Support Desk, poi fornisci a Grok Bot il relativo bot.md e shared/message-safety.md come istruzioni permanenti. Compila Your settings e Knowledge, abilita la skill del canale e usa il suo Routine prompt per il passaggio 2.

Per default, le risposte dei template sono bozze.

Se non parte alcuna esecuzione, confronta l'URL Webhook e la sender key della routine con i valori in Bird.

Crealo dalla CLI o dalla API

Webhook connectors elenca per ogni connettore i campi, quali sono segreti, gli eventi accettati e la configurazione da completare prima, e bird webhooks create --connector <id> --request-schema stampa gli stessi campi come JSON Schema. Passa i campi non segreti con --field name=value e ogni segreto con --credential name=FILE da un file, oppure con --credential name=- passato in pipe su stdin, così non resta nella cronologia della shell. Per default, --events include tutti gli eventi messaggio accettati dal connettore.

Per Claude, crea una chiave API nello spazio di lavoro in cui gira il tuo agente, poi leggila in una variabile di shell senza stamparla a video e passala in pipe, così non compare mai in una riga di comando o nella cronologia della 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> fa tutto questo in un solo passaggio. Indica i campi che mancano ancora al connettore, crea il webhook e stampa l'ID del webhook, gli eventi e il filtro della casella di posta, senza alcun segreto. In next indica bird webhooks test per il webhook, che verifica i campi con la piattaforma. Tramite MCP, webhooks_create con connector_id fa lo stesso in una sola chiamata, e il suo next indica la chiamata webhooks_test.

Per inviare all'agente le email di una sola casella di posta, aggiungi --mailbox con l'ID o l'indirizzo della casella; un indirizzo viene cercato, e per questo serve lo scope mailbox:read. Questo imposta filter.mailbox_id, e --events include allora per default gli eventi della casella elencati dall'azione del connettore, oppure email_mailbox.message_received per un'azione che accetta tutti gli eventi. Per Grok Bot, sostituisci YOUR_MAILBOX_ADDRESS e YOUR_ROUTINE_WEBHOOK_URL con la tua casella di posta e il webhook URL della routine, e incolla la sender key della routine quando read la richiede:

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"

Ogni consegna email_mailbox.message_received contiene il messaggio in data: data.message_id, data.mailbox_id e data.thread_id, il mittente in data.from, i destinatari in data.to e data.subject, che è null quando il messaggio non ne aveva. data.extracted_text è il corpo senza la cronologia citata, null quando non c'è testo, con un limite di 64 KB; data.truncated_text è true quando è stato troncato. Il riferimento degli eventi elenca tutti i campi.

La API accetta gli stessi destination su POST /v1/webhooks. 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, esegui bird webhooks test <webhook_id> oppure chiama POST /v1/webhooks/{webhook_id}/test; una creazione o un aggiornamento dalla CLI o dalla API indica questo passaggio in next. Il salvataggio del webhook non contatta la piattaforma, quindi è il test a verificarne i campi. Per Claude Managed Agents il test legge l'agente invece di avviare una sessione, e così conferma la chiave API e l'agent ID, e riporta kind: probe; quando la risposta individua un valore errato, field lo indica. Una verifica di questo tipo non invia alcun evento, quindi il primo messaggio reale è il controllo end-to-end. Per Grok Bot il test avvia un'esecuzione della routine con un evento contrassegnato come "test": true, quindi verifica in Cursor che un'esecuzione sia partita. Poi invia un messaggio reale a uno dei tuoi numeri o canali e verifica che l'agente lo gestisca; per Claude, verifica che la risposta arrivi sul canale del mittente e che la sessione non mostri alcun session.error.

Gestiscilo

• Ruota una credenziale. Modifica il webhook e inserisci solo il nuovo valore; un campo lasciato vuoto mantiene il valore memorizzato. Dalla CLI, esegui bird webhooks update <webhook_id> --credential name=FILE, oppure passa il valore in pipe con --credential name=-. Tramite la API, invia la chiave aggiornata in PATCH /v1/webhooks/{webhook_id} destination.connector.credentials. La consegna successiva la usa, nuovi tentativi inclusi.
• Modificane le impostazioni. Modifica il webhook, oppure esegui bird webhooks update <webhook_id> --field name=value, per cambiare un'impostazione come l'agent ID, il vault ID o il webhook URL di una routine Grok Bot; la consegna successiva la usa. Per cambiare piattaforma, crea un nuovo 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

• MCP Events, per un client MCP che si iscrive direttamente a questi eventi
• Webhook ed eventi
• Server MCP
• Configura il tuo coding agent
• Superagent: valuta le email in arrivo, i messaggi SMS e WhatsApp prima che il tuo agente li gestisca.