Encaminhe mensagens para seu agente de IA

Bird envia cada mensagem que você recebe por WhatsApp, SMS, Apple Messages ou uma caixa de correio de agente para seu agente de IA. Conecte o agente uma vez com seus dados e credenciais, e cada nova mensagem chegará até ele.

Dois agentes são suportados:

• Claude Managed Agents: cada mensagem inicia uma sessão de um agente que você criou no Claude Console.
• Grok Bot: cada mensagem aciona uma das suas rotinas do Grok Bot.

Bird envia cada mensagem correspondente para seu agente e tenta novamente uma entrega que falhar, então uma mensagem reenviada pode iniciar outra execução. O agente recebe o JSON do evento da mensagem, o mesmo payload que um endpoint de webhook comum recebe, e responde por meio das ferramentas que você disponibilizou, como o servidor Bird MCP.

Escolha as mensagens que seu agente responde

Seu agente pode responder apenas mensagens recebidas: whatsapp.received, sms.received, amb.received (Apple Messages) e email_mailbox.message_received. Selecione as que o agente deve tratar. Confirmações de entrega, mudanças de status e outros eventos não são enviados para um agente.

Claude Managed Agents

1. No Claude Console, crie um agente, um ambiente e uma chave API.
2. No Bird, crie um webhook, escolha Claude Managed Agents e selecione as mensagens em Triggers.
3. Em Connect, insira o ID do agente, o ID do ambiente e a chave API e depois crie o webhook.
4. Selecione Send test.
5. (Opcional) Para permitir que o agente responda pelo Bird, abra o agente no Claude Console, selecione + MCP Server e escolha Bird. Para reduzir o uso de tokens do agente, ative apenas as ferramentas do Bird que ele usa, conforme descrito em Claude Managed Agents.
6. (Opcional) Abra Managed Agents > Credential vaults, crie um cofre, selecione + Add credential, defina Type como MCP OAuth, escolha Bird e selecione Connect.
7. (Opcional) Insira o ID do cofre (que começa com vlt_) em Connect ou edite um webhook existente para adicioná-lo.

Grok Bot

1. Instale o Bird no Grok Bot e conecte seu espaço de trabalho do Bird.
2. Peça ao Grok Bot que crie uma rotina com um gatilho de webhook. Abra a seção Webhook da rotina e copie a URL e a chave do remetente.
3. Crie o webhook no Bird de uma destas formas:
   • Peça ao Grok Bot que o crie com um destino Grok Bot para um evento como amb.received ou email_mailbox.message_received, usando a URL e a chave do remetente da etapa 2. Para e-mail, informe a caixa de correio.
   • Crie-o no painel: escolha Grok Bot, selecione o evento em Triggers e cole a URL e a chave do remetente em Connect.
4. Selecione Send test e depois envie uma mensagem real para sua empresa ou caixa de correio.

Comece a partir de um template (opcional). Antes da etapa 2, escolha AMB Booking Desk ou Email Support Desk e dê ao Grok Bot o bot.md e o shared/message-safety.md do template como instruções permanentes. Preencha Your settings e Knowledge, ative a skill do canal e use o Routine prompt do template na etapa 2.

Por padrão, as respostas dos templates são geradas como rascunhos.

Se nenhuma execução for iniciada, compare a URL de Webhook e a chave do remetente da rotina com os valores no Bird.

Crie pela CLI ou API

Conectores de webhook lista os campos de cada conector, quais deles são secretos, os eventos que ele aceita e a configuração prévia necessária, e bird webhooks create --connector <id> --request-schema exibe os mesmos campos como um JSON Schema. Passe campos não secretos com --field name=value e cada segredo com --credential name=FILE a partir de um arquivo, ou com --credential name=- redirecionado pelo stdin, para que ele fique fora do histórico do shell. Por padrão, --events inclui todos os eventos de mensagem que o conector aceita.

Para o Claude, crie uma chave API no espaço de trabalho em que seu agente roda, depois leia-a em uma variável do shell sem exibi-la e redirecione-a para o comando, para que ela nunca apareça em uma linha de comando ou no histórico do 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> faz tudo isso em uma única etapa. Ele indica qualquer campo que o conector ainda exija, cria o webhook e exibe o ID do webhook, os eventos e o filtro de caixa de correio, sem nenhum segredo. Em next, ele indica bird webhooks test para o webhook, que verifica os campos com a plataforma. Pelo MCP, webhooks_create com connector_id faz o mesmo em uma única chamada, e seu next indica a chamada webhooks_test.

Para enviar os e-mails de uma caixa de correio ao agente, adicione --mailbox com o ID ou o endereço da caixa; um endereço é consultado, o que exige o escopo mailbox:read. Isso define filter.mailbox_id, e então --events passa a incluir por padrão os eventos de caixa de correio listados pela ação do conector, ou email_mailbox.message_received para uma ação que aceita todos os eventos. Para o Grok Bot, substitua YOUR_MAILBOX_ADDRESS e YOUR_ROUTINE_WEBHOOK_URL pela sua caixa de correio e pela URL de webhook da rotina, e cole a chave do remetente da rotina quando read solicitá-la:

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 traz a mensagem em data: data.message_id, data.mailbox_id e data.thread_id, o remetente em data.from, os destinatários em data.to e data.subject, que é null quando a mensagem não tinha nenhum. data.extracted_text é o corpo sem o histórico citado, null quando não há texto, e limitado a 64 KB; data.truncated_text é true quando o corpo foi cortado. A referência de eventos lista todos os campos.

A API aceita o mesmo destination em POST /v1/webhooks. Omita url: Bird o constrói a partir do conector. Nenhuma resposta inclui as credenciais.

Teste a conexão

Logo após criar o webhook, selecione Send test. Depois, use Send test event na página do webhook ou nas ações da linha, execute bird webhooks test <webhook_id> ou chame POST /v1/webhooks/{webhook_id}/test; uma criação ou atualização feita pela CLI ou pelo API indica essa etapa em next. Salvar o webhook não contata a plataforma, então é o teste que verifica os campos. No Claude Managed Agents, o teste lê o agente em vez de iniciar uma sessão, o que comprova a chave API e o ID do agente, e informa kind: probe; quando a resposta identifica um valor incorreto, field indica qual é. Uma verificação desse tipo não envia nenhum evento, então a primeira mensagem real é a verificação de ponta a ponta. No Grok Bot, o teste inicia uma execução da rotina com um evento marcado como "test": true, então verifique no Cursor se uma execução foi iniciada. Em seguida, envie uma mensagem real para um dos seus números ou canais e confirme que o agente a processa; no Claude, confirme que a resposta chega ao canal do remetente e que a sessão não mostra nenhum session.error.

Operação

• Rotacione uma credencial. Edite o webhook e insira apenas o novo valor; um campo deixado em branco mantém o valor armazenado. Pela CLI, execute bird webhooks update <webhook_id> --credential name=FILE ou redirecione o valor com --credential name=-. Pela API, envie a chave alterada em PATCH /v1/webhooks/{webhook_id} destination.connector.credentials. A próxima entrega já a utiliza, incluindo novas tentativas.
• Altere as configurações. Edite o webhook, ou execute bird webhooks update <webhook_id> --field name=value, para alterar uma configuração, como o ID do agente, o ID do cofre ou a URL de webhook de uma rotina do Grok Bot; a próxima entrega já a utiliza. Para trocar de plataforma, crie um novo webhook.
• Pause ou remova. Pausar um webhook interrompe suas entregas. Excluí-lo apaga suas credenciais.
• Leia as falhas. A lista de tentativas de um webhook mostra cada entrega com o status e o corpo da resposta da plataforma, ou nenhum quando não foi possível alcançar a plataforma. Uma tentativa que falhou antes de Bird enviar qualquer coisa, como uma conexão alterada após o evento, traz um failure_reason no lugar.

Próximos passos

• MCP Events, para um cliente MCP que assine esses eventos diretamente
• Webhooks e eventos
• Servidor MCP
• Configure seu agente de código
• Superagent: pontue e-mails recebidos, mensagens SMS e WhatsApp antes que seu agente atue sobre elas.