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

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.