Novidades

Só entram aqui mudanças que afetam a sua integração. As que exigem ação da sua parte dizem o que trocar.

Outubro de 2026: avisos de falha e de armazenamento, resposta de conectar

O error de number.connect.failed é uma frase fixa: para cada reason o campo traz sempre a mesma frase em inglês, no lugar do texto livre que o campo trazia antes, e que mudava de uma versão para outra. Decida pelo reason e use o error só nos seus logs. A lista de frases está em Webhooks. O texto de pairing_timeout mudou de novo.
storage.degraded tem listas fechadas: reason é sempre healthcheck_failed e error_code é um destes: access_denied, bucket_unreachable, region_mismatch, endpoint_unreachable, endpoint_url_blocked, network_error, quota_exceeded, object_not_found, provider_unavailable ou unknown_error. Cada valor tem o que significa e o que fazer em Webhooks. Trate um error_code que você não conhece como unknown_error.
Conectar e desconectar respondem 202 com alias, status e at, nas quatro rotas: POST /v1/numbers/{ref}/connect e /disconnect respondiam 200 com at vazio, e as rotas do número principal respondiam 202 sem o campo. As quatro devolvem agora 202 Accepted com alias, status (connecting ou disconnecting) e at, o instante em que o pedido foi aceito. Quem conferia 200 nas rotas de número extra precisa aceitar 202. O status atual do número e o at dele continuam em GET /v1/numbers/{ref}. Veja Conexão de números extras.

Outubro de 2026: remoção agendada

Remover não exige desconectar: DELETE /v1/numbers/{ref} aceita um número conectado e não responde mais 400 invalid_status_for_deletion. Quando a remoção é agendada, o número continua conectado e funcionando, com o status de sempre, até a data. Veja Remoção.
A data é o fim do período já pago: scheduled_deletion_at passa a ser o fim do período da assinatura (ou o momento do pedido, quando não há período pago), não mais um ciclo de 30 dias do número.
pending_deletion deixou de ser um status, incompatível: status mostra só o estado real da conexão e ?status=pending_deletion em GET /v1/numbers responde 422. Quem testava esse valor precisa ler scheduled_deletion_at, que agora vem em todo item de GET /v1/numbers (null no número principal e nos extras sem remoção) e na resposta do PATCH. Veja Status.
Conectar e desconectar nunca cobram nem mexem na remoção: POST /v1/numbers/{ref}/connect não cancela mais uma remoção agendada nem cobra a ativação, e saíram da tabela de erros dessa rota no_payment_method, payment_declined, payment_requires_authentication e payment_gateway_unavailable. Quem mantém o número é POST /v1/numbers/{ref}/cancel-deletion, que só cobra o que falta do período pago quando a fatura do próximo período já saiu sem o número.
cancel-deletion devolve o estado real: a resposta traz status (o estado da conexão) e at (pode ser null), no lugar de pending_deletion_canceled.
Servidor MCP: nenhuma ferramenta gera cobrança. connect_number deixou de ser a exceção (reconectar um número com exclusão agendada cancelava a exclusão e podia cobrar) e disconnect_number segue sem cobrar. Cancelar uma remoção continua fora do catálogo. Veja Servidor MCP.

Outubro de 2026: pareamento por QR code

Parear um número extra por QR code, pela API: POST /v1/numbers/{ref}/pair aceita agora method: "qr", além de "pairing_code" (o padrão, quando o corpo é omitido). Outro valor responde 422. Na nota do lançamento, "qr" respondia 422: isso mudou. O dashboard já oferecia os dois métodos. Veja Pareamento pela API e Pareamento pelo dashboard.
pairing.method pode ser qr: em GET /v1/numbers/{ref}, com method: "qr", pairing.data é a imagem do QR code em PNG, como data URI (data:image/png;base64,...), para usar como src de um <img>, nunca como texto. Se a sua tela só tratava código, confira pairing.method antes de mostrar pairing.data.
O QR code se renova: o WhatsApp troca o QR code sozinho e o Turbo Notify mantém pairing.data atualizado. Consulte de novo e troque a imagem a cada consulta. Para os dois métodos, pairing.expires_at é o fim da tentativa inteira.
Substituir a tentativa: POST /v1/numbers/{ref}/pair enquanto o número está em pairing substitui a tentativa em andamento, inclusive uma iniciada no dashboard, e pode trocar o método.
Texto neutro de timeout: o data.error de number.connect.failed com reason: "pairing_timeout" não fala mais em “Pairing code expired”. Agora diz que o pareamento não foi concluído a tempo, para código e para QR code. Os motivos pairing_timeout, code_generation_failed e paired_phone_mismatch valem para os dois métodos. Veja Status.

Outubro de 2026: edição de legendas

Editar a legenda de uma imagem, vídeo ou documento: POST /v1/numbers/{ref}/messages/{id}/edit aceita agora caption (1 a 1.024 caracteres, com as mesmas menções @<numero> de um envio). O arquivo continua como estava e quem recebe vê a legenda nova marcada como editada. O desfecho chega como message.edited (com o content_type do arquivo e a legenda nova em preview) ou message.edit.failed. Veja Editar legenda.
O que pode ser alterado depois do envio: texto, a legenda de uma imagem, vídeo ou documento e eventos de calendário podem ser editados. Localização, cartão de contato, botão de link, figurinha e áudio não podem: apagar é a única alteração. Um corpo que não combina com a mensagem responde 400 message_not_editable e um texto ou uma legenda editado mais de 15 minutos depois do envio responde 400 edit_window_expired. Veja O que pode ser alterado depois do envio.
Prazo para editar texto e legenda: o WhatsApp dá 15 minutos, depois do envio, para alterar um texto ou uma legenda. Depois disso a API responde 400 edit_window_expired, em vez de aceitar uma edição que o destinatário pode nunca ver. Os 15 minutos não valem para evento de calendário, embora o WhatsApp ainda possa recusar uma edição de evento.
Corrigido: uma legenda editada no aplicativo do WhatsApp chegava ao webhook como message.edited com preview vazio. Agora traz a legenda nova e o content_type do arquivo.
Servidor MCP, incompatível: a ferramenta edit_message foi removida. Quatro ferramentas a substituem, uma por ação: edit_text_message, edit_media_caption, edit_calendar_event e cancel_calendar_event. Cada uma recebe só os campos do próprio tipo. O servidor passa a ter 36 ferramentas. Agentes que chamavam edit_message precisam chamar a ferramenta do tipo da mensagem. Veja Servidor MCP.

Outubro de 2026: eventos de calendário

Editar e cancelar um evento enviado: POST /v1/numbers/{ref}/messages/{id}/edit aceita agora, além de text, o corpo de um evento de calendário (name, start_at e os demais campos do envio) e o campo canceled. A edição substitui o evento inteiro. O desfecho chega como message.edited (com content_type: "calendar" e canceled: true quando cancelado) ou message.edit.failed. Antes, editar um evento respondia 400 message_not_editable. Veja Editar e apagar.
Eventos editados no aplicativo do WhatsApp: quando quem criou o evento o edita ou cancela no aplicativo, você recebe message.edited com origin: "native".
Respostas dos convidados: o novo evento message.calendar_responded traz a resposta (going, not_going ou maybe) e, quando há, o número de convidados extras. Veja Eventos de calendário.
Ler as respostas: GET /v1/numbers/{ref}/messages/{message_id}/responses devolve a última resposta de cada convidado e os totais. Veja Consultar respostas de um evento.
Códigos novos: message_not_calendar (consulta de respostas em uma mensagem que não é um evento) e message_secret_unavailable (falha de edição de um evento que o número não pode mais alterar). Quando a plataforma não consegue alterar nem cancelar eventos no momento, message.edit.failed traz calendar_edit_unavailable: envie um novo evento. Veja Códigos de erro.

Outubro de 2026: lançamento

API de WhatsApp: envio de texto, mídia, localização, contato, evento de agenda e botão de link; respostas, reações, edição e exclusão; recibos de entrega e leitura; contatos e grupos por número. Veja o Começo rápido.
Eventos por webhook assinado ou por polling, com o mesmo formato.
Servidor MCP com 36 ferramentas para agentes de IA, que você acessa entrando com a sua conta ou com uma chave. No endereço hospedado, uma chamada sem login nem chave agora recebe 401 com o convite para entrar (antes recebia 200 com erro dentro da ferramenta), e um valor que não é nem um login nem uma chave também recebe 401. Veja Construa um agente de IA.
Revenda: números extras, o filtro status na listagem de números e o template de chave Revenda. Cada número tem um id fixo (num_…) que vale no lugar do alias em qualquer rota /v1/numbers/..., vem nos eventos como number_id (e como data.id nos eventos number.*) e filtra a consulta de eventos com ?number_id=. Veja Revenda para seus clientes.
Listagem de mensagens com filtros: GET /v1/numbers/{ref}/messages aceita group_id, contact_id e direction, e cada item traz o mesmo envelope do evento da mensagem (inclusive number_id). Veja Listar mensagens.
Calendário: o evento enviado como calendar agora aparece no WhatsApp do destinatário, em conversa e em grupo. Antes, a mensagem era entregue e não aparecia no aparelho.
Referência interativa da API, índice de códigos de erro e coleção para Insomnia.
Erros de autenticação: chave ausente, mal formatada, desconhecida, revogada ou expirada responde 401 not_authenticated, com o cabeçalho WWW-Authenticate: Bearer; 403 fica para chave válida sem permissão (insufficient_scope). Antes do lançamento, esses casos respondiam 403 not_authorized: se a sua integração de testes tratava esse código, troque para o 401. Veja o índice de códigos de erro.
Avisos de cota: message.quota.warning e contact.quota.warning trazem o limiar atingido em data.threshold_percent (80, 90 ou 95, em porcentagem). Antes do lançamento o campo se chamava threshold_bps, com os mesmos valores: se a sua integração de testes lia esse nome, troque para threshold_percent. Veja Eventos de cota de mensagem.
Novo número extra e pareamento (se a sua integração de testes usava os nomes antigos, ajuste): o corpo de POST /v1/numbers recebe o telefone em phone_number (o nome phone deixou de ser aceito e responde 422), e o corpo de POST /v1/numbers/{ref}/pair só aceita method: "pairing_code" (o "qr" respondia sem efeito e agora responde 422). Veja Adicionar números e Pareamento pela API.
Falhas de serviços de apoio: quando a API não consegue falar com um serviço de que depende, a resposta é 503 service_unavailable; quando um serviço externo responde com erro (por exemplo, o processador de pagamento ao cadastrar um número extra), a resposta é 502 integration_error. Antes, alguns casos devolviam códigos internos que não fazem parte do contrato. Veja o índice de códigos de erro.
Servidor MCP: abrir uma conexão de streaming sem login nem chave responde 401 not_authenticated, com WWW-Authenticate: Bearer, como na API (antes o código era unauthorized). Veja Servidor MCP.
Transcrição de áudio: quando o provedor de transcrição configurado na sua conta não é suportado, data.transcription.reason é provider_not_supported (antes do lançamento era no_adapter). Os demais valores de reason não mudaram. Veja Consultar mensagem.
Documentação em português e em inglês.