Versões e notas de versão da API

Como ler as notas

• Novo: rota, campo ou escopo adicionado.
• Quebra: o comportamento de algo que existia mudou. Revise a integração.
• Correção: um erro foi consertado e o comportamento correto é o que está descrito.

Outubro de 2026

08/10/2026: envio no estilo Blip e fidelidade de comandos

• Novo: POST /messages e POST /notifications na raiz do endereço, no formato de envelope da Blip. Resposta 202 sem corpo quando aceita. Recusas por regra voltam como HTTP 200 com notificação failed.
• Novo: POST /commands na raiz, com Authorization: Key. Escopo ausente responde HTTP 200 com failure 66 nesse perfil.
• Novo: a chave "Compatível com a Blip" na criação.
• Novo: mais caminhos de comando: histórico do cliente (/threads), contatos em lista, etiquetas por nome, atribuição a atendente, cadastros em leitura, relatórios e contadores, agendamentos e modelos.
• Quebra (só no perfil Blip da raiz): a chave de roteador deixa de ver o Desk dos serviços. Em /v1 isso não mudou.
• Quebra (só no perfil Blip da raiz): o contexto de uma chave de roteador passa a ser o contexto compartilhado do roteador.

08/10/2026: correções de segurança e robustez

• Novo: limite de 20 falhas de autenticação por minuto por IP, com 429 e Retry-After.
• Correção: POST /v1/attachments só lê o corpo depois de autenticar. Sem credencial válida, 401 imediato.
• Correção: nomes de campo inválidos em filtros dos comandos (constructor, __proto__) dão failure 64 em vez de erro 500.
• Correção: telefones sem + em comandos de contato têm os não dígitos removidos.
• Novo: a chave pode ter lista de IPs permitidos (ip_permitidos), com 403 ip_not_allowed.

07/10/2026 e 08/10/2026: paridade com a Blip

• Novo: POST /v1/contacts/:id/tickets e POST /v1/tickets para abrir ticket por chave, adotando a sessão do bot.
• Novo: GET /v1/bot-sessions e GET /v1/contacts/:id/bot-session para achar contatos presos no bot.
• Novo: contexto e bloco do contato: GET/PUT/DELETE /v1/contacts/:id/context[/:name] e PUT /v1/contacts/:id/bot-state.
• Novo: GET/POST /v1/schedules e GET/DELETE /v1/schedules/:id.
• Novo: leitura de webhooks (GET /v1/webhooks) e de modelos (GET /v1/channels/:id/templates).
• Novo: relatórios por chave: GET /v1/reports/attendance, effort, satisfaction, history e GET /v1/monitoring/summary, com o escopo relatorios:ler.
• Novo: filtros de histórico em GET /v1/conversations (closed, from, to, label_id, sequential_id) e fechamento como cliente (closedBy: "cliente").
• Novo: GET /v1/contacts/:id/messages com a conversa inteira do contato, incluindo o bot.
• Novo: Idempotency-Key, limite de chamadas por chave e auditoria das escritas por chave.
• Novo: campanhas por chave em /v1/campaigns.
• Quebra: POST /v1/agents/status exige atendentes:escrever. Quem tinha só atendentes:ler recebe 403 without_scope.
• Quebra: POST /v1/contacts agora cria ou encontra o contato. Repetir o telefone devolve 200 com created: false, em vez de criar outro contato. Para o comportamento estrito, use ?upsert=false, que responde 409 se o contato existir.
• Novo e migração: chaves de fluxo passam a nascer com filas:ler, atendentes:ler e contatos:escrever. As chaves de fluxo que já existiam receberam os mesmos três escopos por migração.

Mensagens e mídia

• Novo: reações (POST /v1/conversations/:id/messages/:messageId/reaction), o evento de webhook mensagem.reacao e o estado de entrega reproduzida.
• Novo: mensagens de localização e de contato e botões dinâmicos de modelo.
• Novo: errorText em português para os códigos de erro da Meta mais comuns.
• Quebra: texto acima de 4096 caracteres passa a dar 422 text_too_long.
• Quebra: mídia que o WhatsApp não aceita é recusada com 422 (por exemplo, áudio WAV) ou reclassificada (imagem GIF vira documento), com o aviso em warning.