Pular para o conteúdo principal

Changelog

Mudanças que afetam quem integra. Novidades sem impacto em contrato não entram aqui.

Como lemos "mudança que quebra"​

MudaÉ quebra?
Campo novo, opcional, na respostanão
Campo novo, opcional, na requisiçãonão
Endpoint novonão
Valor novo em um enumnão — trate valores desconhecidos com um caso padrão
Campo removido da respostasim
Campo opcional virou obrigatóriosim
Tipo de um campo mudousim
Código de status mudousim

Quebras só acontecem em uma versão maior da API, com aviso prévio por e-mail para todas as contas ativas.

2.2.0​

Tudo nesta versão é aditivo.

Agências e workspaces​

  • GET /workspaces — o grupo de uma agência, com o consumo de cada cliente no período de cobrança. Só com a chave sem restrição da conta da agência.
  • GET /account/me traz parent: a agência que gerencia e paga a conta, quando ela é o workspace de um cliente.
  • Dentro de um workspace, /wallet e /affiliate respondem 409 billed_by_parent.

Ver Agências e workspaces.

2.1.0​

Tudo nesta versão é aditivo: nada que já funcionava deixa de funcionar.

Endpoints novos​

  • Contatos e consentimento — /contacts, campos personalizados, tags, importação em lote e /suppressions. Ver Contatos e consentimento.
  • Disparo de fluxos — POST /flows/{id}/trigger, com GET /flows e GET /flows/{id}. Ver Fluxos pela API.
  • Campanhas e públicos — /broadcasts e /audiences. Ver Campanhas.
  • Inbox — /inbox, com o stream em tempo real. Ver Inbox.
  • GET /plans/quote, GET /audit/operator-access, GET /wallet, GET /wallet/entries, GET /affiliate e GET /affiliate/referrals.

Eventos novos​

contact.created, contact.opted_in, contact.opted_out, broadcast.completed, broadcast.paused, flow.run.completed, flow.answer.captured, conversation.assigned e conversation.closed. Ver Catálogo de eventos.

Campos e headers novos​

  • POST /messages aceita Idempotency-Key. Ver Repetir sem duplicar.
  • Todo 402 traz action, com o que fazer e onde. Ver Erros.
  • O limite de requisições passou a ser por chave, debaixo de um teto da conta. Respostas trazem X-RateLimit-Scope, e o 429 traz error.scope. Ver Limites de uso.
  • GET /billing traz subscriptions, uma por assinatura da conta. O campo antigo subscription continua, marcado como obsoleto.
  • Planos ganharam stackable, currencyPrices, rateLimits e os tetos de contatos, campanhas e inbox.

2.0.0​

Versão maior — exige mudança no seu código

As rotas antigas não respondem mais. Não há alias: o caminho antigo devolve 404, ou 405 quando ele sobrevive com outro método.

Um endpoint de envio​

O que mudava entre um texto e um template era o tipo da mensagem, que é campo do corpo — não caminho. As rotas por tipo viraram uma só, com type.

AntesAgora
POST /messages/send/textPOST /messages com {"type":"text"}
POST /messages/send/templatePOST /messages com {"type":"template"}
POST /messages/send/testPOST /messages com {"type":"test"}
POST /messages/text, /template, /testidem — os atalhos não documentados saíram

O resto do corpo não mudou: to, from, body, name, language e components seguem iguais. As respostas de sucesso e de erro, também.

Agendamento​

O mesmo POST /messages aceita sendAt (instante ISO 8601) ou delaySeconds e responde 202. Novos: GET /messages/scheduled, GET /messages/scheduled/{id} e DELETE /messages/scheduled/{id}. Ver Enviar mensagens.

Paginação uniforme​

Toda listagem passou a aceitar ?limit= e ?offset= e a responder { data, total, limit, offset }. Quem lia res.data continua funcionando; quem contava com a ausência de total, não.

Endpoints novos​

GET /account/senders, GET /account/usage, DELETE /account/wabas/{id}, GET /audit, GET /plans (público, sem credencial), GET /billing, GET /billing/invoices, GET /billing/license e POST /templates/media.

Eventos de cobrança​

billing.past_due, billing.blocked e billing.restored — os primeiros eventos que nós originamos, em vez de repassar da Meta. Ver Catálogo de eventos.

Outras mudanças de contrato​

  • POST /auth/logout virou DELETE /auth/session.
  • Os dois /revoke de convite viraram DELETE no próprio recurso.
  • Método errado num caminho existente responde 405 com header Allow, onde antes respondia 404.
  • 402 passou a trazer reason, incluindo o novo license_expired.

Saíram da documentação​

Os endpoints que estavam marcados como "em breve" foram retirados da referência: eles respondiam 404 e a referência passa a descrever só o que existe. Imagem, vídeo, documento, botões, lista, CTA, carrossel, localização, contato, reação, figurinha, "digitando…" e "marcar como lida" continuam disponíveis pelo espelho POST /v1/{phone_number_id}/messages, que aceita o payload da Cloud API inteiro — ver Os outros tipos de mensagem.

1.0.0​

Primeira versão pública.

API simplificada — envio por tipo de mensagem, com o número de origem resolvido a partir do token. Listagem, criação e remoção de templates com validação prévia de variáveis e exemplos. Chaves de API com criação e revogação imediata.

Espelho /v1 — contrato da Meta Cloud API byte a byte. Basta trocar o domínio e o token de uma integração existente.

Webhooks — entrega assinada com HMAC-SHA256 sobre "{timestamp}.{corpo}", seis tentativas com backoff de 60s a 6h, log de entregas e reenvio manual.

Coexistência — número compartilhado entre o aplicativo WhatsApp Business e a Cloud API, com sincronização de histórico e contatos nas primeiras 24 horas.

Limites de uso — 500 envios por minuto, 60 uploads de mídia por minuto, 60 consultas por minuto, com os headers X-RateLimit-* em toda resposta.