O que muda na API

A Meta recusa qualquer mensagem livre fora da janela de 24h. Até agora a tentativa saía daqui, era recusada lá e o erro ficava só no log: o atendente via a mensagem como enviada.

O que muda:

• Se o texto que o atendente escreveu corresponde a um modelo aprovado, o envio sai como modelo e a conversa reabre. As variáveis são extraídas do próprio texto, então ele pode editar o modelo antes de mandar.
• Se não corresponde, nada é enviado: uma nota privada explica o motivo e a mensagem fica marcada como falha.
• POST /chatwoot/templates/sync publica os modelos aprovados como respostas prontas (atalho tpl_<nome>), que é como o atendente dispara um sem sair do painel.

Quando não sabemos quando o cliente falou pela última vez, o envio segue normalmente — a Meta continua sendo quem decide.

O account_id era descoberto pelo perfil do Token de Acesso, que devolve a conta ativa do usuário — e ela não tem relação com a conta dona da caixa de entrada configurada. Num bot de automação que atende dezenas de contas com um token só, isso apontava para a conta errada.

Agora a conta é descoberta procurando o inbox_identifier configurado nas caixas de entrada de cada conta que o token enxerga. Quando a varredura não acha a caixa em nenhuma delas, nada é escrito: o log explica o motivo, em vez de a mensagem ir parar na conversa de outro cliente.

Nenhuma ação é necessária de sua parte. Se a sua integração estava funcionando, ela continua igual.

Uma auditoria da integração encontrou cinco problemas, todos corrigidos:

• Mensagem do cliente sumia quando a mídia não podia ser baixada (arquivo acima de 40 MB, download recusado). O Chatwoot recusa mensagem sem conteúdo e sem anexo, e a conversa ficava sem rastro. Agora chega um aviso no lugar do silêncio.
• Riscos de entregue e lido nunca funcionaram no WhatsApp não oficial: dependiam de uma configuração do seu webhook que nasce desligada. O recibo agora vai direto ao Chatwoot.
• Contato identificado só por LID virava um telefone inventado, e a resposta do atendente não chegava a ninguém.
• Do segundo anexo em diante, nada era enviado quando o atendente anexava vários arquivos. E todo documento chegava ao cliente como file.pdf, em vez do nome real.
• Envio recusado pelo provedor ficava com cara de entregue no painel; agora aparece como falha.

A rota tinha dois defeitos que se somavam.

Em conta oficial (Cloud API) ela respondia 500: por dentro, passava pela sessão do QR Code, que a conta oficial não tem. Era justamente a instância cujo webhook dá mais trabalho a que não conseguia ser diagnosticada. Em instância de QR Code ainda não carregada no servidor, o "não encontrada" também saía como 500.

E quando respondia, os números eram os contadores da fila do processo — globais, compartilhados por todas as instâncias daquele servidor. Respondiam "a fila está entupida?", nunca "o webhook da minha instância saiu, e o meu servidor respondeu o quê?". A única resposta para isso vivia no log do servidor, fora do seu alcance.

Agora a resposta é sobre a sua instância:

{
  "status": 200,
  "data": {
    "official": true,
    "webhook": {
      "allowNumber": "all",
      "webhookFormat": "meta",
      "configured": ["webhookMessage", "webhookMessageFromMe"],
      "anyUrl": true
    },
    "delivery": {
      "queued": 118,
      "attempts": 118,
      "ok": 117,
      "clientError": 0,
      "failed": 1,
      "avgMs": 143,
      "last": { "ts": "2026-10-14T22:34:01.020Z", "status": 200, "ms": 131, "outcome": "ok" },
      "recent": []
    },
    "queue": { "waiting": 0, "active": 0, "failed": 0, "scope": "worker-global" }
  }
}

Como ler:

• anyUrl: false — nenhum canal tem URL. Sem URL não há o que entregar: o evento sai só pelo socket. É a causa nº 1 de "não recebo nada", e era o que obrigava a abrir log para descobrir o óbvio. configured diz quais canais têm URL de fato.
• ok alto e ainda assim "não chega nada" — o POST saiu e o seu servidor respondeu 2xx. O evento se perdeu no seu processamento, não no transporte. Esse era o caso que não deixava rastro nenhum.
• clientError — o seu servidor recusou com 4xx. Não retentamos 4xx por desenho: 404 ou 422 não melhora repetindo.
• failed — timeout, 5xx ou 429. Esses nós retentamos: 5 tentativas com backoff exponencial. O nosso tempo limite de entrega é de 8 segundos.
• queued muito acima de attempts — a fila travou do nosso lado. O problema não é o seu servidor.
• queue continua na resposta, agora marcada scope: "worker-global": são números do processo, compartilhados com outras instâncias. Para julgar a sua, use delivery.

Letras miúdas: os contadores valem a partir desta versão, não há histórico retroativo. Ficam 7 dias, e recent traz as últimas 20 entregas com status, duração e erro. Vale para conta oficial (Cloud API) e QR Code.

No mesmo lote, /instance/webhook/error saiu da documentação — ela aparecia lá e nunca existiu na API.

• Enviar reação (/message/reaction com provider: messenger) descartava o emoji e mandava um valor fixo: a Meta respondia 100/2018468 em todas as tentativas. Agora vai o emoji que você enviar. O formato aceito é o emoji em UTF-8 (👍, ❤️); nomes em texto (like) são recusados na hora, com explicação. Remover continua sendo text: "".
• Receber reação não era entregue: o evento era descartado antes de chegar ao seu webhook. Agora chega como mensagem type: "reaction", com reaction.message_id, reaction.emoji e reaction.action (react ou unreact; na remoção o emoji vem vazio).
• Figurinha chegava como imagem comum. O Messenger a entrega como anexo que se declara image com sticker_id no payload; agora chega como type: "sticker" com o id. O arquivo animado não é exposto pela Meta no webhook — a URL servida é a versão estática.
• Foto do contato: quando a Graph recusa o perfil, o motivo passa a ser registrado no log, em vez de o contato ficar sem avatar sem explicação.

A API pública da caixa de entrada aceita apenas texto e anexo. Com Token de Acesso, a mensagem do cliente passa a ser criada pela Application API, o que destrava três coisas:

• Citação nativa: a resposta aparece no balão do Chatwoot, não mais como um trecho citado dentro do texto.
• Nota de voz com player próprio, em vez de um anexo de áudio qualquer.
• Horário real da mensagem: o backlog reentregue depois de uma queda de conexão não aparece mais todo empilhado na hora da entrega.

Sem Token de Acesso nada muda. Citações a mensagens anteriores a esta versão aparecem sem o balão, porque elas não têm o identificador do canal gravado.

Três sinais que existiam nas duas pontas e não se encontravam:

• Atendente digitando → cliente vê. No WhatsApp não oficial é presença; na conta oficial o indicador vai junto do marcar-como-lida, como a Cloud API exige. "Parou de digitar" não existe na conta oficial: lá o indicador some sozinho em cerca de 25 segundos.
• Cliente digitando → atendente vê no painel. O indicador nunca abre conversa nova.
• Responder pelo painel marca como lida no canal, então o cliente deixa de ver dois riscos cinzas enquanto já está sendo atendido.

A entrega dos webhooks é paralela: a ordem em que as requisições chegam ao seu servidor é a ordem em que cada uma completa, não a ordem em que os eventos entraram. Duas mensagens enviadas em sequência podem chegar invertidas.

Em vez de serializar a entrega, os eventos de Messenger passam a carregar:

"wame": {
  "seq": 42,
  "event_ms": 1760000000000,
  "received_at_ms": 1760000000420,
  "dispatched_at_ms": 1760000000437
}

• seq é um contador por conversa, atribuído na ordem em que recebemos o evento da Meta. Ordenar por ele reconstrói a sequência, inclusive quando os horários são iguais.
• event_ms é o horário do evento segundo a Meta, em milissegundos; received_at_ms, quando ele entrou aqui; dispatched_at_ms, quando saiu daqui. A diferença entre o primeiro e o segundo é latência da Meta; entre o segundo e o terceiro, nossa.

O bloco é aditivo: nenhum campo existente mudou. Por enquanto só nos eventos de Messenger.

No mesmo lote, GET /messenger/webhook-fields mostra quais campos de webhook a sua Página assina e POST no mesmo caminho assina os que faltam — é o que explica recibo de entrega, de leitura ou reação que nunca chegam.