Mudanças da API

O que mudou, em ordem, e o que isso exigiu de quem já estava integrado. Só entra aqui o que afeta o contrato: campo novo, endpoint novo, formato diferente. Melhoria interna que não muda nada para você fica de fora, senão a página vira ruído.

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

Escrito aqui para você saber o que pode confiar e o que precisa tolerar.

Isso pode mudar sem versão novaIsso só muda em versão nova
Campo NOVO numa resposta.Campo existente sumir ou trocar de nome.
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.
Duas consequências práticas: ignore campo que você não conhece em vez de rejeitar a resposta, e trate erro pelo code, nunca pela message. Quem faz assim não é afetado por nada da primeira coluna.

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

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

Esta página é a fonte. A especificação OpenAPI acompanha o código: comparar duas versões dela é o jeito mais rápido de ver o que mudou na forma dos campos. E o catálogo de erros lista todos os code em uso, que é o que vale para o seu tratamento.