Início rápido

Crie uma chave de API e envie sua primeira mensagem de WhatsApp em menos de 30 segundos.

Este guia leva você de zero a uma mensagem de WhatsApp enviada. Você pode usar curl ou o SDK oficial para Node.js.

Pré-requisitos

Antes de começar, você precisa de:

• Uma conta no painel da Routa.
• Um canal conectado. Um canal é um número de WhatsApp ligado ao seu projeto. Conecte-o no painel; a conexão é feita pelo fluxo guiado de Embedded Signup.
• Para usar o SDK: Node.js 22 ou superior.

Ainda não há endpoint para conectar canais pela API. Conecte o número no painel e use o id do canal (chan_...) nas chamadas.

Envie sua primeira mensagem

1. Crie uma chave de API

   No painel, acesse Configurações → Chaves de API e crie uma chave para o seu projeto. A chave começa com rt_live_ ou rt_test_ e é exibida uma única vez. Copie e guarde em um local seguro.

   export ROUTA_API_KEY="rt_live_..."
   

   Saiba mais em Autenticação.

2. Confirme que a chave funciona

   GET /v1/whoami não tem efeitos colaterais e retorna a organização, o projeto e os escopos da chave.

   cURL

   curl https://api.routa.chat/v1/whoami \
     -H "Authorization: Bearer $ROUTA_API_KEY"
   

   Resposta

   {
     "organization_id": "org_01J8...",
     "project_id": "proj_01J8...",
     "api_key_id": "key_01J8...",
     "scopes": ["messages:read", "messages:write"]
   }
   
3. Envie uma mensagem

   Informe o canal, o destinatário em formato E.164 e o texto. O header Idempotency-Key garante que uma retentativa não gere uma segunda mensagem.

   cURL

   curl https://api.routa.chat/v1/messages \
     -H "Authorization: Bearer $ROUTA_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{
       "channel": "chan_01J8...",
       "to": "[phone]",
       "text": "Olá! Seu pedido foi confirmado."
     }'
   

   Resposta (202 Accepted)

   {
     "id": "msg_01J8...",
     "channel": "chan_01J8...",
     "direction": "outbound",
     "from": "[phone]",
     "to": "[phone]",
     "content": { "type": "text", "body": "Olá! Seu pedido foi confirmado." },
     "status": "accepted",
     "metadata": {},
     "accepted_at": "2026-09-04T13:22:40.812Z",
     "sent_at": null,
     "delivered_at": null,
     "read_at": null,
     "failed_at": null
   }
   
4. Acompanhe a entrega

   status: "accepted" significa que a Routa recebeu a mensagem, não que ela chegou ao destinatário. A mensagem avança por sent, delivered e read (ou failed). Consulte o estado atual a qualquer momento:

   curl https://api.routa.chat/v1/messages/msg_01J8... \
     -H "Authorization: Bearer $ROUTA_API_KEY"
   

   Em produção, receba cada etapa por webhooks em vez de consultar a API repetidamente.

Aceitar uma mensagem não confirma a entrega. Nunca trate 202 Accepted como mensagem entregue. Veja o ciclo de vida da mensagem.

Próximos passos

Receba eventos por webhook

Registre um endpoint HTTPS e receba message.delivered, message.read e message.received.

Envie templates

Envie mensagens com templates aprovados pelo WhatsApp.

Trate erros

Entenda o formato de erro e quais falhas valem uma nova tentativa.

Referência da API

Todos os endpoints, parâmetros e respostas.