Pular para o conteúdo principal

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:

RequisitoPor quê
Única por interação, dentro do canalDuas conversas diferentes com a mesma chave: a segunda seria lida como reenvio da primeira e descartada.
Estável entre enviosSe a chave muda, a plataforma não reconhece a continuação e cria uma interação nova — cobrada.
Até 120 caracteresLimite do campo.
Não vaziaRecusada 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.

O canal faz parte da identidade

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:

  1. Procura a versão atual da interação com aquela chave e canal.
  2. Não achou → cria. resultado: "Criada", 201.
  3. Achou e o conteúdo é idêntico → resultado: "Duplicada", 200, mesmo interacaoId.
  4. Achou, o conteúdo mudou e a conversa é parcial → cria versão nova. Ver Conversa que continuou.
  5. 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 urlAudio mudou.

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 devolve Duplicada e não atualiza os metadados da interação já gravada.
Metadado errado não se corrige por reenvio

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çãoFazer
Timeout, conexão recusada, 5xxReenviar com backoff exponencial. Sugestão: 5s, 30s, 2min, 10min, 1h.
201 ou 200Sucesso. Registrar e seguir.
400Não reenviar igual — o payload está errado. Corrigir e reenviar.
401Não reenviar — a chave precisa ser trocada. Ver Autenticação.

Detalhe em Erros e retry.