Skip to main content
Uma mensagem representa uma comunicação em qualquer direção: outbound (enviada por você) ou inbound (recebida de um cliente). Ela é independente do provedor: o mesmo objeto serve para qualquer canal presente ou futuro.

​
O objeto mensagem

Use metadata para ligar a mensagem ao seu domínio, por exemplo o ID do pedido. Ele é devolvido na consulta e nos eventos.

​
Ciclo de vida

202 Accepted na criação significa apenas accepted. A entrega acontece depois, de forma assíncrona. Só trate a mensagem como entregue ao receber delivered.

​
O status nunca retrocede

Provedores entregam atualizações de status fora de ordem e mais de uma vez. A Routa só aplica uma transição que avança no ciclo, então uma mensagem nunca volta de read para sent porque um aviso antigo chegou atrasado. Você pode escrever if (message.status === 'delivered') sem lógica defensiva de ordenação. failed só é aceito enquanto a mensagem ainda não foi entregue (accepted ou sent).

​
Retentativas não são um status

Se o provedor falha de forma transitória, a Routa tenta de novo sozinha, com espera crescente. Enquanto isso a mensagem permanece accepted. Não existe status queued nem retrying na API pública. Se as tentativas se esgotam, a mensagem vira failed. O motivo aparece na linha do tempo da mensagem no painel.

​
Mensagens recebidas

Uma mensagem inbound nasce com direction: "inbound" e status: "delivered", e gera o evento message.received. Para sinalizar ao remetente que você leu, use POST /v1/messages/{id}/read, que leva a mensagem para read. Conteúdo que a Routa ainda não sabe modelar chega como { "type": "unsupported" }. A mensagem nunca é descartada por ser desconhecida.

​
Tipos de conteúdo

O campo content é um objeto discriminado por type.
Hoje POST /v1/messages envia apenas text e template. Os demais tipos aparecem em mensagens recebidas e no histórico, e você pode lê-los normalmente. Para baixar a mídia de uma mensagem, use o media_id em GET /v1/media/{id}.

​
Validação no aceite

A Routa valida a mensagem no momento do aceite, não no despacho. Isso transforma problemas previsíveis em um erro imediato 422, em vez de um message.failed segundos depois:
  • O canal precisa estar active (channel_inactive).
  • O canal precisa suportar o tipo de conteúdo (capability_unsupported).
  • O destinatário precisa ser um número válido (invalid_recipient).
  • Um template precisa estar aprovado e com o número certo de parâmetros (template_not_approved, template_paused, content_rejected).
  • Informe exatamente um entre text e template (content_rejected).
Veja todos os códigos em Códigos de erro.