Idempotência e reenvio
Reenviar é seguro. Esta é a regra mais importante desta página, e o resto explica por quê.
Se uma chamada deu timeout e você não sabe se chegou, reenvie. O pior caso é 200 com
resultado: "Duplicada" e o mesmo interacaoId — nada foi criado, nada foi cobrado.
A chave externa
A chaveExterna identifica a interação dentro do canal. Duas ingestões com a mesma chave e o
mesmo canal falam da mesma interação.
Requisitos:
| Requisito | Por quê |
|---|---|
| Única por interação, dentro do canal | Duas conversas diferentes com a mesma chave: a segunda seria lida como reenvio da primeira e descartada. |
| Estável entre envios | Se a chave muda, a plataforma não reconhece a continuação e cria uma interação nova — cobrada. |
| Até 120 caracteres | Limite do campo. |
| Não vazia | Recusada com 400. |
Use o id que a origem já tem. O id do chat no WhatsApp, o id do bilhete no discador, o número do protocolo. Não invente um id novo por envio, e não use timestamp: os dois quebram a estabilidade.
Uma conversa de WhatsApp com chave X e uma ligação com chave X são interações diferentes — a
plataforma considera o canal junto com a chave. Isso é bom (você não precisa coordenar namespaces entre
sistemas), mas quer dizer que a mesma chave em canais diferentes não deduplica.
O que a plataforma compara
Não é só a chave. Ela compara o conteúdo:
- Procura a versão atual da interação com aquela chave e canal.
- Não achou → cria.
resultado: "Criada",201. - Achou e o conteúdo é idêntico →
resultado: "Duplicada",200, mesmointeracaoId. - Achou, o conteúdo mudou e a conversa é
parcial→ cria versão nova. Ver Conversa que continuou. - Achou, o conteúdo mudou, mas a conversa não é
parcial→resultado: "Duplicada",200. Conversa concluída é imutável.
A ordem do array não importa
As mensagens são ordenadas por emitidaEm antes da comparação. Se o seu sistema embaralhar o
array — uma consulta sem ORDER BY, um Promise.all que retorna fora de ordem — o resultado continua
sendo Duplicada, não uma versão nova cobrada.
O que importa é o conjunto de falas, não a sequência em que você as escreveu no JSON.
O que conta como conteúdo diferente
- Uma fala nova.
- O texto de uma fala existente mudou.
- Uma fala saiu.
- Em voz: a
urlAudiomudou.
O que não conta
- Ordem do array (acima).
- Mudança nos
metadados— eles não entram na comparação. Reenviar a mesma conversa com metadados corrigidos devolveDuplicadae não atualiza os metadados da interação já gravada.
Se você mandou campanha errada e a conversa já foi ingerida, reenviar não conserta: o conteúdo é o
mesmo, então é duplicata. O cliente pode ajustar na curadoria dele. Vale conferir os metadados antes
de enviar. Ver Metadados.
Por que a plataforma trabalha assim
A idempotência não é conveniência — é reconhecimento de como mensageria funciona de verdade. Webhook de terceiro erra, rede cai no meio da resposta, fila reentrega, e um operador clica duas vezes. Um sistema que criasse duplicata em qualquer um desses casos empurraria para o parceiro a responsabilidade de garantir entrega exatamente uma vez, que é justamente a garantia que HTTP não dá.
A garantia é reforçada no banco de dados, não só em código: existe uma restrição de unicidade sobre conversa + conteúdo. Mesmo que duas requisições idênticas cheguem no mesmo instante, uma delas é recusada pela infraestrutura antes de qualquer análise ser paga.
Retry recomendado
| Situação | Fazer |
|---|---|
Timeout, conexão recusada, 5xx | Reenviar com backoff exponencial. Sugestão: 5s, 30s, 2min, 10min, 1h. |
201 ou 200 | Sucesso. Registrar e seguir. |
400 | Não reenviar igual — o payload está errado. Corrigir e reenviar. |
401 | Não reenviar — a chave precisa ser trocada. Ver Autenticação. |
Detalhe em Erros e retry.