O que muda na API
Mudanças de endpoint, de envelope de webhook e de comportamento, em ordem cronológica. Campos novos são aditivos: nada que você já recebe deixa de vir sem aviso aqui.
Adição é compatível com o que você já faz. Correção muda o que você recebe na direção do que estava documentado. Requer atenção muda o comportamento de quem não fizer nada.
- CorreçãoInstagramMessenger
Instagram e Messenger: webhook volta a chegar na hora
Em instâncias de WhatsApp por QR Code com Instagram ou Messenger conectado, os eventos desses canais esperavam até 60 segundos e chegavam agrupados. Agora saem em cerca de 1 segundo.
- O que acontecia. Mensagens recebidas, ecos das mensagens enviadas e confirmações de leitura do Instagram e do Messenger podiam ficar até 60 segundos parados antes de sair para o seu webhook. Por isso chegavam em lote, quase todos no mesmo segundo de cada minuto. O WhatsApp da mesma instância não era afetado.
- O que mudou. O evento passa a ser entregue em cerca de 1 segundo depois de chegar da Meta.
- Nada foi perdido. Os eventos do período foram todos entregues, só que com atraso.
Não há nada a configurar do seu lado. Instâncias da API Oficial não eram afetadas.
- AdiçãoInstagramAPI
Webhook do Instagram: número de sequência e carimbos de tempo
Os eventos do Instagram passam a levar o mesmo bloco wame do Messenger: sequência por conversa e três horários para medir onde o tempo foi gasto.
Mensagens, ecos e status do Instagram agora trazem, na raiz do payload:
json"wame": { "seq": 12, "event_ms": 1793810776000, "received_at_ms": 1793810776412, "dispatched_at_ms": 1793810776530 }seqé um contador por conversa, na ordem em que recebemos o evento da Meta. Ordene por ele para reconstruir a sequência quando as requisições chegarem fora de ordem.received_at_ms − event_msé o tempo da Meta até nós;dispatched_at_ms − received_at_msé o nosso. O que sobrar até o seu servidor registrar a chegada é fila de entrega e rede.
event_mssó aparece quando a Meta informa o horário do evento. Oseqrecomeça do 1 depois de algumas horas sem atividade na conversa, então compare só eventos próximos. O bloco é aditivo: nenhum campo existente mudou. - Requer atençãoAPI
Webhook: cabeçalho que identifica o evento e fim das entregas repetidas
Todo POST passa a levar Webhook-Event-Id, o mesmo id em qualquer reentrega do mesmo evento — use-o para descartar o que já processou. Junto, as instâncias da API Oficial ganharam fila própria, e um endpoint lento não segura mais o webhook das outras.
Webhook-Event-Idem todo POST. O valor é derivado do próprio evento (instância, tipo e id da mensagem), nunca sorteado. Isso significa que a mesma mudança reentregue chega com o mesmo id — seja por nova tentativa nossa, por reinício do nosso processo, ou pelo backlog que o WhatsApp reenvia depois de uma reconexão. Guarde o id e descarte o que já processou: é o jeito seguro de não duplicar do seu lado, e é mais barato que comparar o corpo.- A causa mais comum da repetição era o tempo de resposta. Nosso POST tem 8 segundos de limite e até 5 tentativas: um endpoint que processa o evento mas só responde no nono segundo recebia o mesmo evento até cinco vezes, e não havia como distinguir uma cópia da outra. Responda
200primeiro e processe depois — com isso a reentrega deixa de acontecer, e oWebhook-Event-Idcobre o que sobrar. - Reentrega do backlog, depois de reconexão, também era duplicata. O que já tinha saído ao vivo voltava quando a instância reconectava. Agora o evento já entregue é reconhecido e não sai de novo.
- Instâncias da API Oficial passaram a ter fila própria. Antes elas dividiam a fila com as de QR Code: um único endpoint lento acumulava eventos e segurava todas as outras instâncias atrás dele — na prática, o evento demorava, e em alguns casos parava de chegar. As duas filas agora são independentes.
Nada é descartado por engano: na dúvida, o evento é entregue. O cabeçalho é aditivo — quem não ler continua recebendo como antes.
- CorreçãoInstagramMessenger
Áudio para Instagram e Messenger que sumia sem erro
Áudio podia constar como enviado, não chegar e não gerar erro nenhum. Os dois caminhos que causavam isso foram fechados: agora o envio falha na hora, com o motivo.
Áudio enviado para contatos do Instagram e do Messenger podia sumir: a API respondia sucesso, a mensagem não chegava e nenhum erro aparecia em lugar nenhum. Eram dois caminhos, os dois corrigidos:
- Formato recusado saindo mesmo assim. Esses canais só aceitam
aac,m4a,wavemp4. Nós convertemos o que chega em outro formato, mas quando não conseguíamos baixar o arquivo para converter (URL privada, link expirado, tempo esgotado), o áudio seguia no formato original — e ummp3era aceito pela Meta e descartado por ela em silêncio. Agora, se o arquivo não pode ser baixado e a extensão não é uma das aceitas, o envio falha na hora e diz o porquê. - Resposta sem identificador tratada como sucesso. A Meta devolve o id da mensagem em todo envio que ela realmente criou. Quando vinha uma resposta sem esse id, nós devolvíamos sucesso — e a mensagem não existia do outro lado. Agora isso volta como erro, com a resposta dela junto.
Nada muda para quem envia áudio em formato aceito.
- Formato recusado saindo mesmo assim. Esses canais só aceitam
- CorreçãoWhatsApp Oficial
Refazer a conexão volta a trazer contatos e conversas
Na coexistência com o WhatsApp Business, refazer a conexão do número deixava a importação do histórico ser pulada em silêncio. Agora ela acontece sozinha.
Na coexistência com o WhatsApp Business, quem refazia a conexão do número não recebia de novo o histórico de contatos e conversas: a importação era pulada em silêncio, e só o suporte conseguia destravá-la manualmente.
A causa era nossa contagem: a Meta permite uma importação de cada tipo por janela, e nós continuávamos contando a janela anterior. Refazer a conexão emite credenciais novas — agora reconhecemos isso como um começo novo e a importação acontece sozinha, dentro da janela que a Meta abre.
Quem conectou o número uma vez só e já tem o histórico não é afetado: nenhuma importação extra é disparada.
- CorreçãoAPI
Reiniciar instância: chamadas repetidas não atropelam mais o reinício em curso
Chamar o reinício várias vezes disparava reinícios concorrentes que competiam entre si. Agora a resposta diz em quantos segundos tentar de novo, e traz o campo restarted.
Chamar o reinício da instância várias vezes seguidas disparava reinícios concorrentes, que competiam entre si e atrasavam a reconexão — exatamente o contrário do que se espera de quem está tentando reconectar. É o caso típico de monitoramento automático que chama o endpoint a cada leitura de "desconectado".
Agora, se já houver um reinício em curso, a resposta diz em quantos segundos tentar de novo, em vez de iniciar outro. A resposta ganhou o campo
restarted, que informa se este pedido iniciou um reinício (true) ou encontrou um já em andamento (false).Se você automatiza reinício, respeite esse tempo. Reiniciar em excesso faz o WhatsApp reentregar o backlog de mensagens, e é uma das causas de evento repetido no seu webhook.
- CorreçãoWhatsApp Oficial
Template com botão de formulário (Flow) pode ser criado e enviado
O envio de template com botão de Flow era recusado pela Meta. Agora o bloco que ela exige é montado automaticamente, e a resposta traz o flowToken que liga o formulário preenchido ao envio.
Template que tem botão de formulário (Flow) era recusado no envio: a Meta exige um bloco próprio para esse botão, e quem chamava a API não tinha como saber disso.
Enviar. Nada muda na sua chamada — o bloco é montado por nós:
POST /message/template { "to": "5566999999999", "name": "agendar_horario", "language": "pt_BR" }A resposta passa a trazer
flowToken, o identificador que liga o formulário preenchido a este envio. Ele aparece junto da resposta emGET /flows/{flowId}/responses— antes, uma resposta vinda de botão de template não tinha como ser atribuída e ficava sem origem. Se preferir um identificador seu (o número do pedido, por exemplo), continue mandando o bloco do botão com o seuflow_token: ele é respeitado e registrado.Criar. O botão passou a ser aceito na criação do template:
json{ "type": "FLOW", "text": "Agendar horário", "flow_id": "1234567890" }Use exatamente um entre
flow_id,flow_nameeflow_json;flow_actionénavigatepor padrão e abre a primeira tela do Flow. Um botão de Flow pela metade — sem texto ou sem Flow — passa a ser recusado na hora, em português, em vez de depois de horas de revisão da Meta.Publique o Flow antes. Com ele em rascunho, a Meta aprova o template e só recusa na hora do envio.
- AdiçãoChatwoot
Conversa que nasce de anúncio chega com o anúncio junto no Chatwoot
A conversa espelhada no Chatwoot passa a começar com o título, o texto e a mídia do anúncio que a originou, antes da mensagem da pessoa.
Quando alguém fala com você clicando num anúncio, a conversa espelhada no Chatwoot agora começa com o contexto do anúncio — título, texto e o link da imagem ou do vídeo — antes da mensagem da pessoa. Antes chegava só "quero saber o preço", e o atendente não tinha como saber de qual anúncio.
Vale para anúncios que levam ao WhatsApp e para os que levam ao Instagram Direct. Os dois canais entregam campos diferentes (o do WhatsApp traz título, texto e miniatura; o do Instagram traz o título do anúncio e a mídia), e os dois são lidos.
Quem consome pelo webhook já recebia esses dados no campo
referrale continua recebendo, sem mudança. Vale conferir qual forma você lê: oreferraldo Instagram não tem os mesmos campos do WhatsApp — ali o título vem emads_context_data.ad_title, e a mídia emphoto_urlouvideo_url. - AdiçãoInstagramMessenger
Ver quais envios do Instagram e do Messenger não chegaram
Novo GET /instance/sends: lista os envios recentes com o que a Meta respondeu e marca, com missingEcho, os que ela confirmou e depois descartou em silêncio.
Instagram e Messenger confirmam o envio na hora e só depois buscam a mídia por conta deles. Quando essa busca falha, a mensagem é descartada sem erro e sem webhook — do seu lado e do nosso, o envio parecia ter dado certo. O único sinal de que a mensagem existe de verdade é a confirmação que a Meta devolve logo em seguida.
GET /{sua-chave}/instance/sendsDevolve os envios recentes, do mais novo para o mais antigo, com o que a Meta respondeu e se a confirmação dela chegou.
missingEcho: truemarca o envio que a pessoa não recebeu.onlyMissing=true— só os que sumiram.limit— quantos voltam (padrão 50, máximo 200).
Os registros ficam guardados por 7 dias. Um envio recém-feito aparece sem confirmação por até um minuto: ela costuma levar alguns segundos, e só depois disso o envio é dado como não entregue.
- AdiçãoWhatsApp
Formulário nativo no WhatsApp, link que abre dentro do app e botões de catálogo
Novos tipos de mensagem interativa: formulário de múltiplas etapas respondido dentro do WhatsApp, botão de link em webview e os três formatos de catálogo. Junto, duas regras de renderização que valem para quem já usa carrossel e cobrança.
- Formulário nativo (
form_message): até 3 perguntas, cada uma com até 5 alternativas, respondidas dentro do WhatsApp sem sair da conversa. Cada pergunta aceita resposta única ou múltipla, e pode liberar resposta escrita pelo usuário. A resposta chega no seu webhook identificada por pergunta — o identificador é derivado do texto que você escreveu ("Como avalia nosso atendimento?"→como-avalia-nosso-atendimento), ou o que você informar. Os limites de 3 e 5 são do WhatsApp: acima disso o aparelho do destinatário mostra formulário quebrado, então a API recusa na entrada, com explicação. - Botão de link que abre dentro do WhatsApp: o botão de URL ganhou a opção de webview. Com ela a página abre embutida na conversa, no celular, em vez de jogar o usuário no navegador. No WhatsApp Web não existe webview — lá o link abre em aba, como sempre.
- Catálogo em três formatos: botão que abre o catálogo inteiro, botão que abre um produto específico, e o compartilhamento de catálogo no formato que o próprio aplicativo do WhatsApp envia (
wa.me/c). Os três dependem de catálogo configurado na conta business; sem isso o cartão não é desenhado. - Cobrança: item que não vem do seu catálogo passa a ser enviado marcado como item avulso. Antes, o WhatsApp Web procurava a linha no catálogo, não encontrava, e o painel "detalhes do pagamento" ficava carregando sem fim para o seu cliente. Se você cobra por valor digitado — o caso mais comum —, era exatamente o seu caso.
- Carrossel: card sem imagem não é desenhado no WhatsApp Web. O cartão chega e os botões funcionam, mas quem abre pelo Web vê "não foi possível carregar a mensagem". Com imagem no cabeçalho, o carrossel aparece normalmente nos dois. Isso sempre foi assim; passou a estar documentado.
- Botões no formato antigo não aparecem no iPhone. O formato legado de botões renderiza no WhatsApp Web e não no iOS, em nenhuma variação — é limitação do aplicativo, não da API. Para botão de resposta que funciona em todo lugar, use os botões de resposta rápida.
- Formulário nativo (
- Requer atençãoChatwootWhatsApp Oficial
Janela de 24h: mensagem livre fora dela deixa de ser enviada
Na conta oficial, passadas 24h da última mensagem do cliente, o texto livre não é mais tentado: ou sai como modelo aprovado, ou vira aviso na conversa.
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/syncpublica os modelos aprovados como respostas prontas (atalhotpl_<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.
- CorreçãoChatwoot
Chatwoot: a conta passa a ser descoberta pela caixa de entrada
Quem usa um único Token de Acesso para várias contas do Chatwoot tinha as mensagens enviadas pelo celular escritas na conta errada — ou recusadas com 404.
O
account_idera 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_identifierconfigurado 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.
- CorreçãoChatwootWhatsAppWhatsApp Oficial
Chatwoot: cinco falhas no espelho das conversas
Mensagem com mídia que não pôde ser baixada deixava de aparecer no painel; riscos de entregue/lido não funcionavam no WhatsApp não oficial; anexos além do primeiro eram descartados.
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.
- CorreçãoAPIWhatsApp Oficial
Diagnóstico de webhook: a rota de estatísticas passa a falar da sua instância
GET /instance/webhook/statistics respondia 500 em conta oficial e, quando respondia, devolvia os contadores da fila do servidor — iguais para todas as instâncias. Agora devolve o resultado real de cada POST da sua instância.
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:
json{ "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.configureddiz quais canais têm URL de fato.okalto 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.queuedmuito acima deattempts— a fila travou do nosso lado. O problema não é o seu servidor.queuecontinua na resposta, agora marcadascope: "worker-global": são números do processo, compartilhados com outras instâncias. Para julgar a sua, usedelivery.
Letras miúdas: os contadores valem a partir desta versão, não há histórico retroativo. Ficam 7 dias, e
recenttraz as últimas 20 entregas com status, duração e erro. Vale para conta oficial (Cloud API) e QR Code.No mesmo lote,
/instance/webhook/errorsaiu da documentação — ela aparecia lá e nunca existiu na API. - CorreçãoMessenger
Messenger: reações passam a funcionar, e figurinha deixa de chegar como imagem
O endpoint de reação enviava um valor fixo em vez do emoji escolhido, e toda tentativa era recusada pela Meta. Reação recebida e figurinha também não chegavam identificadas.
- Enviar reação (
/message/reactioncomprovider: messenger) descartava o emoji e mandava um valor fixo: a Meta respondia100/2018468em 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 sendotext: "". - Receber reação não era entregue: o evento era descartado antes de chegar ao seu webhook. Agora chega como mensagem
type: "reaction", comreaction.message_id,reaction.emojiereaction.action(reactouunreact; na remoção o emoji vem vazio). - Figurinha chegava como imagem comum. O Messenger a entrega como anexo que se declara
imagecomsticker_idno payload; agora chega comotype: "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.
- Enviar reação (
- AdiçãoChatwoot
Chatwoot: citação nativa, nota de voz e horário real
Com Token de Acesso configurado, a conversa no painel passa a ter balão de resposta de verdade, player de voz e o horário em que a mensagem existiu no canal.
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.
- AdiçãoChatwootWhatsAppWhatsApp Oficial
Chatwoot: “digitando…” nos dois sentidos e risco azul ao responder
O cliente passa a ver quando o atendente está digitando, o atendente passa a ver quando o cliente digita, e responder pelo painel marca a conversa como lida no WhatsApp.
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.
- AdiçãoMessengerAPI
Webhook do Messenger: número de sequência e carimbos de tempo
Cada evento passa a levar um bloco wame com um número de sequência por conversa e três horários, para reconstruir a ordem e medir onde o tempo foi gasto.
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:
json"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-fieldsmostra quais campos de webhook a sua Página assina ePOSTno mesmo caminho assina os que faltam — é o que explica recibo de entrega, de leitura ou reação que nunca chegam.