Skip to main content
Ao final, seu backend envia uma mensagem a cada etapa do pedido (confirmado, enviado, entregue, pagamento recusado) e sabe quando alguma não chegou.

Antes de começar

  • Chave de API na variável ARARA_API_KEY. Ver Autenticação.
  • Número conectado na organização. Ver Números.
  • Templates UTILITY aprovados (o passo 1 cria). Ver Templates.
  • Webhook configurado para receber o status de entrega. Ver Webhooks.
  • Telefone do cliente em E.164 (+5511999999999). (11) 99999-9999 precisa ser convertido antes.

Passo a passo

1

Crie os templates

Um template UTILITY por etapa. Exemplo do primeiro:
Repita para os outros três, trocando name, body, samples e buttons:
  • samples é um objeto com o número da variável como chave.
  • No botão de URL, {{N}} reaproveita a variável N do corpo. Só o trecho depois da última / do valor entra no link. Passe um identificador simples (id do pedido, código de rastreio), não uma URL inteira.
  • A resposta traz o id (UUID). Acompanhe a aprovação com GET /v1/templates/{id}/status ou pelo webhook template.updated.
2

Envie em cada etapa do pedido

A Idempotency-Key vem do pedido e da etapa. Se o seu job rodar de novo (retry, webhook reenviado pela loja), a Arara devolve a mensagem original em vez de enviar outra.
A API responde 202 com { id, status, mode, sender, receiver, body, cost, reason }. Guarde o id (ara_msg_...) junto do pedido para casar com o webhook.
3

Acompanhe a entrega

O status chega pelo webhook message.status_updated, em minúsculas: queued, processing, scheduled, sent, delivered, read, failed, canceled.
Valide a assinatura antes de processar (ver Webhooks). Com failed, leia errorDetails. Se o número não recebe WhatsApp, caia para e-mail ou SMS no seu sistema. Ver Erros de envio.

Armadilhas

Em POST /v1/messages a idempotência não compara o conteúdo. A mesma chave com outro destinatário ou outras variáveis devolve a mensagem original, sem erro. Para reenviar de propósito (o cliente corrigiu o telefone, por exemplo), use outra chave. A chave não expira e vale por usuário dono da chave de API.
  • Template não abre a janela de 24h. Ela abre quando o cliente responde. A partir daí o Brain ou o seu time respondem.
  • Oferta de nova compra é MARKETING. Não coloque cupom em template UTILITY: crie um template MARKETING separado e envie só para quem aceitou receber marketing.

Próximos passos

Atendimento com vários atendentes

Quem atende quando o cliente responde.

Carrinho abandonado

Recupere quem não chegou a virar pedido.

Eventos de webhook

Payload de cada evento.