Enruta mensajes a tu agente de IA

Bird envía cada mensaje que recibes en WhatsApp, SMS, Apple Messages o un buzón de agente a tu agente de IA. Conecta el agente una vez con sus datos y credenciales, y cada mensaje nuevo le llega.

Se admiten dos agentes:

• Claude Managed Agents: cada mensaje inicia una sesión de un agente que creaste en la Claude Console.
• Grok Bot: cada mensaje activa una de tus rutinas de Grok Bot.

Bird envía cada mensaje coincidente a tu agente y reintenta una entrega que falla, por lo que un mensaje reintentado puede iniciar otra ejecución. El agente recibe el evento del mensaje JSON, el mismo payload que recibe un endpoint de webhook estándar, y responde con las herramientas que le hayas dado, como el servidor Bird MCP.

Elige los mensajes que responde tu agente

Tu agente solo puede responder mensajes entrantes: whatsapp.received, sms.received, amb.received (Apple Messages) y email_mailbox.message_received. Selecciona los que el agente debe gestionar. Los acuses de recibo, los cambios de estado y otros eventos no se envían a un agente.

Claude Managed Agents

1. En la Claude Console, crea un agente, un entorno y una clave API.
2. En Bird, crea un webhook, elige Claude Managed Agents y selecciona los mensajes en Triggers.
3. En Connect, introduce el ID del agente, el ID del entorno y la clave API, y después crea el webhook.
4. Selecciona Send test.
5. (Opcional) Para que el agente pueda responder a través de Bird, abre el agente en la Claude Console, selecciona + MCP Server y elige Bird. Para reducir su consumo de tokens, activa solo las herramientas de Bird que use, como se describe en Claude Managed Agents.
6. (Opcional) Abre Managed Agents > Credential vaults, crea un almacén, selecciona + Add credential, establece Type en MCP OAuth, elige Bird y selecciona Connect.
7. (Opcional) Introduce el ID del almacén (empieza por vlt_) en Connect, o edita un webhook existente para añadirlo.

Grok Bot

1. Instala Bird en Grok Bot y conecta tu espacio de trabajo de Bird.
2. Pide a Grok Bot que cree una rutina con un trigger de webhook. Abre la sección Webhook de la rutina y copia su URL y su clave de remitente.
3. Crea el webhook en Bird de una de estas formas:
   • Pide a Grok Bot que lo cree con un destino Grok Bot para un evento como amb.received o email_mailbox.message_received, con la URL y la clave de remitente del paso 2. Para el correo electrónico, indica el buzón.
   • Créalo en el panel: elige Grok Bot, selecciona el evento en Triggers y pega la URL y la clave de remitente en Connect.
4. Selecciona Send test y después envía un mensaje real a tu empresa o a tu buzón.

Empieza desde una plantilla (opcional). Antes del paso 2, elige AMB Booking Desk o Email Support Desk y después da a Grok Bot su bot.md y shared/message-safety.md como instrucciones permanentes. Completa Your settings y Knowledge, activa su skill de canal y usa su Routine prompt en el paso 2.

Las respuestas de las plantillas se guardan como borradores por defecto.

Si no se inicia ninguna ejecución, compara la URL de Webhook y la clave de remitente de la rutina con los valores de Bird.

Créalo desde la CLI o la API

Webhook connectors enumera los campos de cada conector, cuáles son secretos, los eventos que acepta y la configuración que debes hacer antes, y bird webhooks create --connector <id> --request-schema muestra los mismos campos como un JSON Schema. Pasa los campos no secretos con --field name=value y cada secreto con --credential name=FILE desde un archivo, o con --credential name=- por stdin mediante una tubería, para que no quede en tu historial de shell. Si no lo indicas, --events incluye todos los eventos de mensaje que acepta el conector.

Para Claude, crea una clave API en el espacio de trabajo donde se ejecuta tu agente. Después léela en una variable de shell sin mostrarla en pantalla y pásala por una tubería, para que nunca aparezca en una línea de comandos ni en tu historial de 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> hace todo esto en un solo paso. Indica cualquier campo que el conector aún necesite, crea el webhook y muestra el ID del webhook, los eventos y el filtro de buzón, sin ningún secreto. En next indica bird webhooks test para el webhook, que comprueba los campos con la plataforma. A través de MCP, webhooks_create con connector_id hace lo mismo en una sola llamada, y su next indica la llamada a webhooks_test.

Para enviar al agente el correo de un solo buzón, añade --mailbox con el ID o la dirección del buzón; una dirección se busca, lo que requiere el alcance mailbox:read. Esto establece filter.mailbox_id, y entonces --events incluye por defecto los eventos de buzón que enumera la acción del conector, o email_mailbox.message_received si la acción acepta todos los eventos. Para Grok Bot, sustituye YOUR_MAILBOX_ADDRESS y YOUR_ROUTINE_WEBHOOK_URL por tu buzón y la URL de webhook de la rutina, y pega la clave de remitente de la rutina cuando read la solicite:

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"

Cada entrega de email_mailbox.message_received incluye el mensaje en data: data.message_id, data.mailbox_id y data.thread_id, el remitente en data.from, los destinatarios en data.to, y data.subject, que es null si el mensaje no tenía. data.extracted_text es el cuerpo sin el historial citado; es null si no hay texto y tiene un máximo de 64 KB. data.truncated_text es true si se recortó. La referencia de eventos enumera todos los campos.

La API acepta los mismos destination en POST /v1/webhooks. Omite url: Bird lo genera a partir del conector. Ninguna respuesta incluye las credenciales.

Prueba la conexión

Justo después de crear el webhook, selecciona Send test. Más adelante, usa Send test event en la página del webhook o en las acciones de su fila, ejecuta bird webhooks test <webhook_id> o llama a POST /v1/webhooks/{webhook_id}/test; al crear o actualizar desde la CLI o la API, este paso se indica en next. Guardar el webhook no contacta con la plataforma, así que la prueba es lo que comprueba sus campos. En Claude Managed Agents, la prueba lee el agente en lugar de iniciar una sesión, lo que verifica la clave API y el ID del agente, e informa de kind: probe; cuando la respuesta identifica un valor incorrecto, field lo indica. Una sonda no envía ningún evento, así que el primer mensaje real es la comprobación de extremo a extremo. En Grok Bot, la prueba inicia una ejecución de la rutina con un evento marcado como "test": true, así que comprueba en Cursor que se inició una ejecución. Después envía un mensaje real a uno de tus números o canales y confirma que el agente lo gestiona; en Claude, confirma que la respuesta llega al canal del remitente y que la sesión no muestra ningún session.error.

Opéralo

• Rota una credencial. Edita el webhook e introduce solo el valor nuevo; un campo que dejes en blanco conserva su valor almacenado. Desde la CLI, ejecuta bird webhooks update <webhook_id> --credential name=FILE, o pasa el valor por una tubería con --credential name=-. A través de la API, envía la clave modificada en PATCH /v1/webhooks/{webhook_id} destination.connector.credentials. La siguiente entrega la usa, incluidos los reintentos.
• Cambia su configuración. Edita el webhook, o ejecuta bird webhooks update <webhook_id> --field name=value, para cambiar un ajuste como el ID del agente, el ID del almacén o la URL de webhook de una rutina de Grok Bot; la siguiente entrega lo usa. Para cambiar de plataforma, crea un webhook nuevo.
• Paúsalo o elimínalo. Pausar un webhook detiene sus entregas. Eliminarlo borra sus credenciales.
• Consulta los fallos. La lista de intentos de un webhook muestra cada entrega con el estado de respuesta y el cuerpo que devolvió la plataforma, o ninguno si no se pudo contactar con ella. Un intento que falló antes de que Bird enviara nada, por ejemplo por una conexión que cambió después del evento, lleva un failure_reason en su lugar.

Próximos pasos

• MCP Events, para un cliente MCP que se suscriba a estos eventos por su cuenta
• Webhooks y eventos
• Servidor MCP
• Configura tu agente de código
• Superagent: puntúa los mensajes entrantes de correo electrónico, SMS y WhatsApp antes de que tu agente actúe sobre ellos.