Changelog

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.

  1. 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.

  2. 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_ms só aparece quando a Meta informa o horário do evento. O seq recomeç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.

  3. 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-Id em 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 200 primeiro e processe depois — com isso a reentrega deixa de acontecer, e o Webhook-Event-Id cobre 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.

  4. 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, wav e mp4. 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 um mp3 era 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.

  5. 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.

  6. 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.

  7. 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 em GET /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 seu flow_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_name e flow_json; flow_action é navigate por 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.

  8. 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 referral e continua recebendo, sem mudança. Vale conferir qual forma você lê: o referral do Instagram não tem os mesmos campos do WhatsApp — ali o título vem em ads_context_data.ad_title, e a mídia em photo_url ou video_url.

  9. 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/sends

    Devolve os envios recentes, do mais novo para o mais antigo, com o que a Meta respondeu e se a confirmação dela chegou. missingEcho: true marca 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.

  10. 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/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.

  11. 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_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.

  12. 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.
  13. 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. 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.

  14. 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/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.
  15. 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.

  16. 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.
  17. 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-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.