Markdown
Referência · versões

Mudanças da API

Acompanhe alterações nos endpoints, nos campos e nas regras de integração.

A regra de compatibilidade (link para esta seção)

Prepare sua integração para novos campos e mensagens de erro, preservando o tratamento dos códigos e formatos já documentados.

Isso pode mudar sem versão novaIsso só muda em versão nova
Campo novo numa resposta.Remoção ou renomeação de um campo existente.
Valor novo num campo de texto livre (ex.: um `reason` inédito).Tipo de um campo mudar.
A frase de `message` num erro.O `code` de um erro mudar de nome.
Endpoint novo.Endpoint existente sumir.
Ignore campos desconhecidos e trate erros pelo code. O texto de message pode mudar sem alterar a condição do erro.

Mudança que quebra contrato ganha caminho novo (/public/v2/) e a v1 continua no ar. As duas quebras marcadas abaixo aconteceram antes de existir cliente integrado além do primeiro, que foi avisado direto; daqui em diante a regra vale.

Histórico (link para esta seção)

2026

Novo

Teste de todos os eventos pelo painel

6 de novembro de 2026
  • Em Integrações → Webhook, escolha entre os cinco eventos habilitados na configuração salva, incluindo contact.marketing_opt_out. Cada teste usa dados fictícios e data.test: true, assinatura normal e identificador próprio.
  • Valide a assinatura e responda 2xx sem gravar ou alterar cadastros quando o marcador for o booleano true. Os exemplos Node.js, PHP e o guia para IA seguem essa regra para todos os eventos. Veja como testar.
  • O teste tem uma tentativa, fica na auditoria e não entra na fila de entregas. Nenhum contato é descadastrado pelo teste na Patrocinio; o receptor também precisa respeitar o marcador.
Novo

Conciliação, consentimento em lote e gestão de templates

6 de novembro de 2026
  • Consulte um envio sem message_id por GET /public/v1/messages/status, usando client_ref ou Idempotency-Key. Resultado incerto ou não encontrado não autoriza gerar outra operação. O contrato informa retenção e limitações.
  • Nova consulta de até 500 contatos por lote e registro explícito de consentimento com data, origem, referência da prova e event_id idempotente. Registros legados não ganham provas inventadas. A API não remove recusa nem bloqueio existente.
  • Campanhas do painel podem ser consultadas por /public/v1/campaigns e /campaigns/{id}/results. Totais e destinatários paginados distinguem aceite, entrega, leitura, falha e saída de promoções.
  • Criação de templates e upload de amostras disponíveis pela API. Novas assinaturas opcionais: contact.marketing_opt_out, template.status e template.quality. O evento message.received também informa a interação e a saída reconhecida de forma estruturada.
  • A consulta de números acrescenta os motivos da restrição e indica leitura antiga. As respostas autenticadas incluem headers de cota. Entregas de webhook aceitam filtros por message_id e evento e informam a retenção aplicada.
Mudou

Resposta do receptor de webhook

6 de novembro de 2026
  • O detalhe de entrega preserva um trecho legível de respostas gzip e deflate, com limite também após a descompressão e ocultação de credenciais conhecidas. O nome last_error permanece por compatibilidade; ele pode conter a resposta mesmo quando o HTTP foi 200.
  • Problemas de leitura do conteúdo comprimido não transformam um HTTP aceito em falha de entrega. A correção vale para novas tentativas; não reenvia eventos antigos nem reconstrói respostas já truncadas.
Novo

Números conectados e referência para IA

6 de novembro de 2026
  • Novo GET /public/v1/numbers: números da empresa, qualidade, capacidade do portfólio e última saúde registrada. Paginação por cursor, até 50 itens, horários por leitura e indicação de indisponibilidade parcial.
  • O guia Integrar com IA reúne instrução copiável, Markdown e OpenAPI. O MCP público oferece busca e leitura da documentação, sem acesso a contas ou ferramentas de envio.
  • Históricos de novos envios preservam até dez botões. Recuperação de um aceite usa o conteúdo salvo naquela operação, sem substituí-lo por um template editado depois. Códigos de autenticação continuam mascarados.
  • Checkpoints antigos sem cópia completa usam apenas os dados comprovados da operação; não recuperamos texto ou botões antigos consultando o catálogo atual.
Mudou

Validação, consentimento e consulta de entrega

6 de novembro de 2026
  • O envio recusa campos desconhecidos, índices que não sejam inteiros e URLs de mídia inválidas. O erro invalid_request pode incluir error.details.fields, com o campo, código e orientação, sem repetir valores sensíveis.
  • Telefones precisam incluir o código do país. Para cadastros locais, use /validate com country; o envio não acrescenta DDI automaticamente.
  • A consulta da janela acrescenta marketing_allowed e marketing_block_reason. Ausência de bloqueio não prova consentimento: aceite pendente continua diferente de aceito, e recusa ou bloqueio impedem marketing.
  • O limite é de 600 requisições por minuto por chave, somando envios e consultas de todos os workers. Em api_rate_limited, respeite Retry-After; o JSON também pode informar error.details.retry_after_seconds.
  • Use GET /public/v1/messages/{message_id}/status para consultar um envio já registrado, sem reenviar. O webhook continua sendo o caminho principal para acompanhar entregas.
  • Mudanças de status, qualidade, categoria e componentes invalidam o catálogo de templates entre os processos da API. As assinaturas opcionais de templates foram acrescentadas posteriormente nesta mesma data, conforme a entrada acima.
Novo

Qualidade e contrato do catálogo de templates

7 de outubro de 2026
  • Cada modelo passa a informar id, quality_score, rejected_reason e message_send_ttl_seconds, com valores nulos quando a Meta não os fornece. O OpenAPI descreve a resposta completa.
  • Use status=ALL para acompanhar análise, aprovação e outros estados. Filtro vazio ou desconhecido retorna 400 invalid_template_status. A consulta não entrega catálogo parcial como se estivesse completo.
  • Aprovação e qualidade continuam independentes. O integrador deve conferir sendable e api_supported antes de preparar um envio.
Mudou

Horários UTC e estado da conta

7 de outubro de 2026
  • Os campos data.occurred_at e data.window_expires_at de message.received passam a indicar UTC explicitamente com Z. O instante representado não muda.
  • A chave da API exige conta ativa ou em avaliação. Suspensão, desativação ou remoção da conta também bloqueiam chamadas autenticadas por chave.
Mudou

Validação de templates, autenticação e proteção contra envio duplicado

6 de outubro de 2026
  • A listagem de templates aceita phone_number_id e informa parameter_format, body.variable_names e buttons[].needs_otp. O envio confere as variáveis, o cabeçalho e os botões antes de chamar a Meta.
  • Novo otp_code com otp_index para templates de autenticação. O código é repetido no corpo e no botão nativo; validade e uso único continuam sob responsabilidade do sistema emissor.
  • Uma chave de idempotência usada com conteúdo diferente retorna idempotency_conflict. Tentativas com resultado incerto não são reenviadas automaticamente após cinco minutos. Registros antigos sem hash retornam idempotency_legacy_unverified.
  • A consulta da janela sem phone_number_id usa o número padrão do envio. A janela permite escolher o formato; não informa gratuidade.
  • O painel permite escolher eventos de status e respostas recebidas sem apagar a seleção existente. O reenvio preserva o identificador da entrega; o consumidor deve deduplicá-lo.
Novo

Idempotência reservada antes do envio, e erros de template separados

11 de agosto de 2026
  • A Idempotency-Key passou a ser reservada antes da chamada à Meta, protegendo também as tentativas concorrentes e as falhas de conexão durante o envio.
  • Resposta nova: 409 idempotency_in_flight, quando outra chamada com a mesma chave ainda está em andamento. Espere alguns segundos e repita com a mesma chave.
  • Uma recusa confirmada permite corrigir o pedido e reutilizar a chave. Falhas de conexão e resultados sem confirmação mantêm a reserva; confira a regra atual em idempotência.
  • invalid_template se dividiu. Agora existem template_params_mismatch (as variáveis não batem: cabeçalho com anexo, botão com link variável ou variável com NOME também precisam ser enviados), template_not_found e template_paused. Cada um pede uma ação diferente, e a mensagem única mandava investigar as três.
  • marketing_experiment: a Meta separa parte dos destinatários num grupo que não recebe marketing, para medir o efeito. Não é falha do envio e reenviar não muda.
Novo

Janela de 24h, templates, anexo no envio e resposta do contato

2 de agosto de 2026
  • GET /public/v1/window/{to}: diz se dá para mandar texto livre agora. É a consulta que orienta a escolha entre texto livre e template.
  • GET /public/v1/templates: lista os seus templates já decompostos em cabeçalho, corpo, rodapé e botões, dizendo o que cada um exige no envio.
  • POST /public/v1/messages ganhou header_media, header_text, button_url_param, variable_names e reply_to_message_id. Sem eles, template com anexo (bilhete, comprovante) ou com botão dinâmico não tinha como ser enviado pela API.
  • Novo evento de webhook message.received: o que o contato respondeu, com o texto, a mídia, a citação e o window_expires_at, que é até quando você pode responder dentro da janela de atendimento.
Novo

Consulta e reenvio das entregas do webhook

30 de julho de 2026
  • GET /public/v1/deliveries, com filtro por status e paginação por cursor (before_id).
  • GET /public/v1/deliveries/{id}, que traz também o corpo do que o seu endpoint respondeu.
  • POST /public/v1/deliveries/{id}/retry e POST /public/v1/deliveries/retry-failed.
  • Especificação OpenAPI pública em /public/v1/openapi.json, só das rotas públicas.
Quebra

Formato do evento de status alinhado

30 de julho de 2026
  • error virou OBJETO {code, message, reason}, no lugar de uma string com um error_code solto ao lado. Quem lia a string precisou passar a ler error.reason.
  • recipient passou a se chamar to, o mesmo nome do campo no envio.
  • timestamp passou a se chamar occurred_at, para não confundir com o X-PT-Timestamp do header, que tem outro significado.
  • Entrou status_rank, para o seu lado descartar evento fora de ordem sem inventar regra própria.
Quebra

Assinatura com timestamp e header de autenticação

30 de julho de 2026
  • A assinatura passou a ser o HMAC de "timestamp" + "." + corpo, e não mais só do corpo. Assinar só o corpo deixava a requisição válida para sempre, então quem capturasse uma entrega poderia reenviá-la meses depois.
  • Um só padrão de assinatura: a versão antiga foi removida em vez de conviver com a nova.
  • Passou a ser possível configurar um header de autenticação próprio do seu endpoint, para gateways que recusam antes de olhar a assinatura.
Novo

Correlação, idempotência e fila de entrega

30 de julho de 2026
  • client_ref no envio, devolvido em todo evento de status. Acaba com a tabela de-para entre o id do WhatsApp e o seu registro.
  • Header Idempotency-Key: repetir a mesma chamada devolve a resposta original em vez de enviar de novo.
  • Limite por CHAVE (600 por minuto) no lugar do limite por IP, que estrangulava campanha grande e misturava clientes atrás do mesmo IP.
  • O webhook ganhou fila com retentativa de cerca de 31 horas. Antes, endpoint fora do ar significava evento perdido.
Novo

Primeira versão da API pública

28 de julho de 2026
  • POST /public/v1/messages: texto na janela de 24h e template fora dela.
  • POST /public/v1/validate: confere o formato do número antes do envio.
  • Webhook de saída com o evento message.status, assinado com HMAC-SHA256.
  • Chaves de API por conta, com prefixo visível e revogação.

Como você fica sabendo (link para esta seção)

Antes de acontecer

Mudança que exige ação sua é avisada por e-mail para o responsável da conta, com prazo. Nada que quebre integração entra sem aviso.

Para acompanhar

Consulte este histórico e a especificação OpenAPI para acompanhar os contratos. O catálogo de erros informa as condições conhecidas e a ação recomendada para cada uma.