Acheminer les messages vers votre agent IA

Bird envoie chaque message que vous recevez sur WhatsApp, SMS, Apple Messages ou une boîte mail d'agent à votre agent IA. Connectez l'agent une seule fois avec ses informations et ses identifiants, et chaque nouveau message lui parvient.

Deux agents sont pris en charge :

• Claude Managed Agents : chaque message démarre une session d'un agent que vous avez créé dans la Claude Console.
• Grok Bot : chaque message déclenche l'une de vos routines Grok Bot.

Bird envoie chaque message correspondant à votre agent et réessaye une livraison qui échoue, de sorte qu'un message réessayé peut lancer une nouvelle exécution. L'agent reçoit le JSON d'événement du message, le même payload qu'un simple point de terminaison webhook reçoit, et répond via les outils que vous lui avez fournis, comme le serveur Bird MCP.

Choisir les messages auxquels votre agent répond

Votre agent peut répondre uniquement aux messages entrants : whatsapp.received, sms.received, amb.received (Apple Messages) et email_mailbox.message_received. Sélectionnez ceux que l'agent doit traiter. Les accusés de réception, les changements de statut et les autres événements ne sont pas envoyés à un agent.

Claude Managed Agents

1. Dans la Claude Console, créez un agent, un environnement et une clé API.
2. Dans Bird, créez un webhook, choisissez Claude Managed Agents et sélectionnez les messages sous Triggers.
3. Sous Connect, saisissez l'identifiant de l'agent, l'identifiant de l'environnement et la clé API, puis créez le webhook.
4. Sélectionnez Send test.
5. (Facultatif) Pour permettre à l'agent de répondre via Bird, ouvrez l'agent dans la Claude Console, sélectionnez + MCP Server et choisissez Bird. Pour limiter sa consommation de tokens, activez uniquement les outils Bird qu'il utilise, comme l'indique la documentation Claude Managed Agents.
6. (Facultatif) Ouvrez Managed Agents > Credential vaults, créez un coffre, sélectionnez + Add credential, définissez Type sur MCP OAuth, choisissez Bird et sélectionnez Connect.
7. (Facultatif) Saisissez l'identifiant du coffre (il commence par vlt_) sous Connect, ou modifiez un webhook existant pour l'y ajouter.

Grok Bot

1. Installez Bird dans Grok Bot et connectez votre espace de travail Bird.
2. Demandez à Grok Bot de créer une routine avec un déclencheur webhook. Ouvrez la section Webhook de la routine et copiez son URL et sa clé d'expéditeur.
3. Créez le webhook dans Bird, de l'une des deux façons suivantes :
   • Demandez à Grok Bot de le créer avec une destination Grok Bot pour un événement tel que amb.received ou email_mailbox.message_received, en utilisant l'URL et la clé d'expéditeur de l'étape 2. Pour l'e-mail, indiquez la boîte mail.
   • Créez-le dans le tableau de bord : choisissez Grok Bot, sélectionnez l'événement sous Triggers et collez l'URL et la clé d'expéditeur sous Connect.
4. Sélectionnez Send test, puis envoyez un vrai message à votre entreprise ou à votre boîte mail.

Partir d'un modèle (facultatif). Avant l'étape 2, choisissez AMB Booking Desk ou Email Support Desk, puis donnez à Grok Bot son fichier bot.md et shared/message-safety.md comme instructions permanentes. Remplissez Your settings et Knowledge, activez sa compétence de canal et utilisez son Routine prompt pour l'étape 2.

Par défaut, les réponses des modèles sont des brouillons.

Si aucune exécution ne démarre, comparez l'URL Webhook et la clé d'expéditeur de la routine avec les valeurs saisies dans Bird.

Créez-le depuis la CLI ou la API

Webhook connectors répertorie les champs de chaque connecteur, indique lesquels sont secrets, les événements qu'il accepte et la configuration à effectuer au préalable, et bird webhooks create --connector <id> --request-schema affiche les mêmes champs sous forme de JSON Schema. Passez les champs non secrets avec --field name=value et chaque secret avec --credential name=FILE depuis un fichier, ou avec --credential name=- transmis par un pipe sur stdin, pour qu'il ne figure pas dans l'historique de votre shell. Par défaut, --events inclut tous les événements de message que le connecteur accepte.

Pour Claude, créez une clé API dans l'espace de travail où votre agent s'exécute, puis lisez-la dans une variable shell sans l'afficher et transmettez-la par un pipe, pour qu'elle n'apparaisse jamais dans une ligne de commande ni dans l'historique de votre 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> effectue tout cela en une seule étape. La commande indique les champs encore requis par le connecteur, crée le webhook, puis affiche l'identifiant du webhook, les événements et le filtre de boîte mail, sans aucun secret. Sous next, elle indique bird webhooks test pour le webhook, qui vérifie les champs auprès de la plateforme. Via MCP, webhooks_create avec connector_id fait de même en un seul appel, et son next indique l'appel webhooks_test.

Pour envoyer les e-mails d'une boîte mail à l'agent, ajoutez --mailbox avec l'identifiant ou l'adresse de la boîte mail ; une adresse est recherchée, ce qui nécessite le scope mailbox:read. Cette option définit filter.mailbox_id, et --events inclut alors par défaut les événements de boîte mail que l'action du connecteur répertorie, ou email_mailbox.message_received pour une action qui accepte tous les événements. Pour Grok Bot, remplacez YOUR_MAILBOX_ADDRESS et YOUR_ROUTINE_WEBHOOK_URL par votre boîte mail et l'URL du webhook de la routine, puis collez la clé d'expéditeur de la routine lorsque read la demande :

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"

Chaque livraison email_mailbox.message_received contient le message sous data : data.message_id, data.mailbox_id et data.thread_id, l'expéditeur dans data.from, les destinataires dans data.to, et data.subject, qui vaut null lorsque le message n'en avait pas. data.extracted_text est le corps sans l'historique cité ; il vaut null en l'absence de texte et est limité à 64 Ko. data.truncated_text vaut true lorsqu'il a été tronqué. La référence des événements répertorie tous les champs.

La API accepte les mêmes destination sur POST /v1/webhooks. Ne renseignez pas url : Bird le construit à partir du connecteur. Aucune réponse n'inclut les identifiants.

Tester la connexion

Juste après avoir créé le webhook, sélectionnez Send test. Par la suite, utilisez Send test event sur la page du webhook ou dans les actions de sa ligne, exécutez bird webhooks test <webhook_id> ou appelez POST /v1/webhooks/{webhook_id}/test ; une création ou une mise à jour depuis la CLI ou le API indique cette étape dans next. L'enregistrement du webhook ne contacte pas la plateforme : c'est le test qui vérifie ses champs. Pour Claude Managed Agents, le test lit l'agent au lieu de démarrer une session, ce qui valide la clé API et l'identifiant de l'agent, et renvoie kind: probe ; lorsque la réponse identifie une valeur erronée, field l'indique. Un test de connexion n'envoie aucun événement : le premier vrai message constitue donc la vérification de bout en bout. Pour Grok Bot, le test lance une exécution de la routine avec un événement marqué "test": true : vérifiez donc dans Cursor qu'une exécution a démarré. Envoyez ensuite un vrai message à l'un de vos numéros ou canaux et confirmez que l'agent le traite ; pour Claude, confirmez que la réponse arrive sur le canal de l'expéditeur et que la session n'affiche aucun session.error.

Exploitation

• Renouveler un identifiant. Modifiez le webhook et saisissez uniquement la nouvelle valeur ; un champ laissé vide conserve sa valeur enregistrée. Depuis la CLI, exécutez bird webhooks update <webhook_id> --credential name=FILE, ou transmettez la valeur par un pipe avec --credential name=-. Via la API, envoyez la clé modifiée dans PATCH /v1/webhooks/{webhook_id} destination.connector.credentials. La livraison suivante l'utilise, nouvelles tentatives comprises.
• Modifier ses paramètres. Modifiez le webhook, ou exécutez bird webhooks update <webhook_id> --field name=value, pour changer un paramètre tel que l'identifiant de l'agent, l'identifiant du coffre ou l'URL du webhook d'une routine Grok Bot ; la livraison suivante l'utilise. Pour changer de plateforme, créez un nouveau webhook.
• Suspendre ou supprimer. Suspendre un webhook arrête ses livraisons. Le supprimer efface ses identifiants.
• Consulter les échecs. La liste des tentatives d'un webhook indique pour chaque livraison le code de statut et le corps de la réponse de la plateforme, ou rien si la plateforme n'a pas pu être jointe. Une tentative qui a échoué avant que Bird n'envoie quoi que ce soit, par exemple une connexion modifiée après l'événement, porte à la place un failure_reason.

Étapes suivantes

• MCP Events, pour un client MCP qui s'abonne lui-même à ces événements
• Webhooks et événements
• Serveur MCP
• Configurer votre agent de développement
• Superagent : évaluez les e-mails entrants, les messages SMS et WhatsApp avant que votre agent n'agisse dessus.