Skip to main content
Mudanças incompatíveis são anunciadas aqui com antecedência e, quando possível, mantidas por período de convivência. Campos novos em respostas e webhooks não contam como incompatíveis, então escreva o seu cliente para ignorar campos desconhecidos.
​
Cobrança PIX recebida
  • Uma cobrança PIX recebida (o cartão “Copiar chave Pix” do WhatsApp Business) chega no received com os dados: o botão de buttons[] passa de type: "other" para type: "pix" e ganha pix com merchant_name, key, key_type, code (copia e cola), amount e currency. O label continua payment_info. Veja buttons recebidos.
  • SDK: type do botão recebido ganha "pix", e o botão ganha pix.
​
Presença do contato mais confiável
  • Com always_online, o Wabox volta a marcar o número como online a cada 5 minutos e a cada consulta de presença, e não só ao conectar. Antes, se o WhatsApp passasse a ver o número como offline depois de conectar, ele parava de mandar a presença dos contatos e o “digitando”.
  • GET /contacts/{phone}/presence renova a assinatura da presença do contato quando ele continua sendo consultado, no máximo uma vez por minuto. Só a primeira consulta espera a resposta.
​
Número certo no envio
  • verify_phone nos envios: todo envio que cria uma mensagem nova aceita verify_phone: true. O Wabox confere o número no WhatsApp antes de enviar e manda para o número em que ele está registrado (por exemplo, com ou sem o nono dígito). Sem conta no WhatsApp, o envio falha com phone_not_on_whatsapp, sem tentar enviar. Veja Número certo no envio.
  • O número conferido fica guardado por 30 dias, renovados a cada uso, e vale para todos os envios a ele, mesmo sem verify_phone. GET /phone-exists/{phone} e POST /phone-exists-batch também alimentam esse cache.
  • delivery ganha canonical_phone, o número para onde a mensagem foi, quando o Wabox o conhece. phone continua como você mandou.
  • SDK: os corpos de envio ganham verify_phone, e o tipo do webhook delivery ganha canonical_phone.
​
Presença do contato
  • GET /contacts/{phone}/presence devolve se o contato está online (status: "AVAILABLE" ou "UNAVAILABLE"), o visto por último (last_seen, quando ele compartilha) e quando chegou a última atualização (momment). A primeira consulta de um contato pede ao WhatsApp para avisar as mudanças dele e espera a resposta por até 3 s. As mudanças seguintes também chegam no webhook chat_presence. Veja a referência.
  • Configuração nova always_online (padrão false): deixa o número online enquanto conectado, o que o WhatsApp exige para mandar a presença dos contatos. Vale depois de um restart. Com o número online, o celular costuma deixar de receber notificações.
  • O webhook chat_presence de online e offline passa a trazer o telefone em phone, em vez do LID, quando o Wabox conhece os dois.
  • Account API: as settings enviadas em POST /account/instances valem desde a primeira conexão. Antes, as de sessão (auto_read_*, call_reject_*, proxy_url) só passavam a valer depois de um restart.
  • SDK: tipo ContactPresence e always_online em InstanceSettings.
​
MCP lê conversas
  • Três tools novas no MCP da conta: list_chats (conversas, com não lidas), read_chat (mensagens de uma conversa) e search_messages (busca por texto, sem diferenciar maiúsculas nem acentos). A leitura junta o histórico do pareamento com as mensagens que a sessão viu desde que iniciou, guardadas só em memória. Veja O que a leitura enxerga.
  • Escopos OAuth novos: messages:read (read_chat, search_messages) e chats:read (list_chats). Autorizações já existentes não os ganham: revogue e conecte o app de novo. Com o token da instância como bearer, as tools aparecem sem mudar nada.
​
Operação no webhook delivery
  • delivery ganha operation, que diz o que o evento reporta: send (mensagem nova), edit, delete, reaction, remove_reaction, pin, unpin, poll_vote ou event_response. Com ele, uma exclusão, edição ou reação que falhou não se confunde com uma falha no envio da mensagem. Veja Falha de uma ação.
  • O message_id das ações é sempre o da mensagem referenciada. Em edições, exclusões, reações e pins, o delivery de sucesso trazia o id interno da mensagem de protocolo. Agora ele traz o mesmo id que a resposta do endpoint devolveu, no sucesso e na falha.
  • SDK: o tipo do webhook delivery ganha operation.
​
Id de mensagem próprio
  • custom_message_id nos envios: todo envio que cria uma mensagem nova aceita um id escolhido por você (de 1 a 128 caracteres ASCII visíveis, sem espaços, como cp_123). A mensagem sai para o WhatsApp com esse id, que vira o message_id da resposta e dos webhooks. Um id repetido na instância responde 409 duplicate_message_id, e o id de um envio que falhou pode ser reutilizado. Veja Usar o seu próprio id.
  • O delivery de falha traz message_id. Antes o campo só vinha nos envios bem-sucedidos; agora falhas como phone_not_on_whatsapp também trazem o id.
  • SDK: os corpos de envio ganham custom_message_id.
​
QR code com prazo
  • O QR code expira depois de ~13 minutos sem leitura. Uma instância que ninguém pareia não fica mais gerando QR para sempre. Ao fim do prazo o pareamento para, a instância vai para disconnected e o webhook instance_status chega com o novo disconnect_reason: "qr_timeout". Para tentar de novo, chame GET /qr-code (ou /qr-code/image, ou /phone-code/{phone}), e o pareamento recomeça do zero, com mais ~13 minutos. No painel, a tela da instância mostra Gerar novo QR code.
  • SDK: disconnect_reason ganha o valor qr_timeout.
​
Webhook instance_status
  • Novo webhook instance_status, enviado a cada mudança de status da instância: starting, qr (aguardando leitura do QR code), connecting, connected, disconnected, logged_out, banned e stopped. Ele traz previous_status, phone (ao conectar), disconnect_reason e reason (ao cair). O evento não traz o QR code: status: "qr" é o sinal para buscar GET /qr-code. Configure em instance_status_url (ou na URL única) e silencie com ignore_instance_status_callback. Veja instance_status.
  • Incompatível: os webhooks connected e disconnected saíram. O instance_status os substituiu, e com eles saíram os campos connected_url, disconnected_url, ignore_connected_callback, ignore_disconnected_callback e PUT /webhooks/connected|disconnected. Quem tinha uma dessas URLs foi migrado para instance_status_url (quem usa URL única não precisa fazer nada), mas o corpo mudou. Troque type: "connected" por type: "instance_status" + status: "connected", e type: "disconnected" + reason por status + disconnect_reason. Campos antigos enviados em PUT /webhooks são ignorados.
  • Todo workspace novo começa em URL única: single_url_enabled nasce true na configuração de webhooks do workspace, e basta preencher single_url. Workspaces já configurados não mudam, e um primeiro PUT /account/webhooks que traga só URLs por tipo desliga o modo sozinho.
  • SDK: WebhookEvent ganha WebhookInstanceStatus e perde WebhookConnected / WebhookDisconnected.
​
API keys do workspace
  • API keys substituem o Client-Token e o Account-Token. Um workspace pode ter várias keys, cada uma com nome e permissões (instances:operate, instances:read, instances:write, webhooks:read, webhooks:write). Você as cria em Segurança › API keys e as envia em Authorization: Bearer wbx_key_…. A key aparece uma vez, na criação. Revogar uma não afeta as outras, então a rotação não tem downtime: crie a nova, publique e revogue a antiga. Veja API keys.
  • Incompatível, Account API: o header Account-Token (act_…) deixou de ser aceito. Crie uma API key com as permissões das rotas que você usa e envie em Authorization: Bearer. Cada rota /account/* agora pede uma permissão (tabela).
  • Compatível, Client-Token: os Client-Tokens existentes foram migrados para uma key chamada “Client-Token (migrado)”, com instances:operate, e continuam funcionando no header Client-Token, que passa a ser um alias de Authorization: Bearer nas rotas de instância (e no /mcp com o token da instância). O estado de “exigir” foi mantido, e o ajuste no painel agora se chama Exigir API key nas rotas de instância.
  • Erros: 401 api_key_required substitui client_token_required e account_token_required. Se o seu código compara esses code, atualize. Novo 403 insufficient_scope, com details.required_scope, quando a key é válida mas não tem a permissão da rota.
  • SDK: createWabox({ apiKey }) no lugar de clientToken e createWaboxAccount({ apiKey }) no lugar de accountToken. Postman: as variáveis client_token e account_token viraram api_key.
​
Account API e plano por slots
  • Account API (/account/*, header Account-Token): contas com plano criam, atualizam e excluem instâncias por API, até o número de slots do plano. GET /account/plan mostra slots usados e livres; sem slot livre, 409 instance_limit_reached; conta em trial, 403 plan_required. Veja Account API.
  • Incompatível: a Account API substitui a Partner API (/partner/*, Partner-Token), que não chegou a ter clientes em produção. No SDK, createWaboxPartner virou createWaboxAccount.
  • A assinatura passa a ser da conta, cobrada por slot, e não mais por instância: subscription_status, trial_ends_at e due_at da instância agora refletem a conta (trial_ends_at é null fora do trial). O trial começa na primeira instância criada e permite uma instância.
​
Documentação pública
  • Documentação em developer.wabox.me, com abas Documentação e API Reference geradas do código da API.
  • Referência com 120 endpoints canônicos (mais aliases de compatibilidade com a z-api) e 6 webhooks documentados a partir dos contratos.
  • Playground com instance_id/token persistidos no navegador.
​
Business e etiquetas
  • Perfil comercial, catálogo (produtos, coleções), pedidos e send-product/send-catalog/send-order/order-status-update, todos best effort.
  • Etiquetas (/labels) em contas Business, com aliases /tags.
  • Webhook received com blocos product e order.
​
Interativos, comunidades, canais e privacidade
  • Botões, OTP, PIX, lista, carrossel, eventos de calendário e status (stories).
  • Comunidades, canais (newsletters) e configurações de privacidade.
  • Assinatura HMAC X-Wabox-Signature em todos os webhooks e POST /webhooks/secret para rotação.
​
Chats, contatos, perfil e grupos
  • GET /chats, ações de chat, mensagens temporárias; contatos, verificação de números em lote e bloqueio; perfil; grupos completos (participantes, links de convite, pedidos de entrada).
​
Mídia e mensagens ricas
  • Imagem, áudio (voice note com forma de onda), vídeo, PTV, GIF, documento e sticker, por URL ou base64, com conversões por ffmpeg.
  • Localização, contatos, link com prévia, reações, encaminhar, fixar, apagar, enquetes e votos, ler, presença.
  • Endpoints de fila (GET/DELETE /queue).
​
Lançamento da API
  • Instâncias com QR code e código de pareamento, send-text, webhooks received, delivery, message_status, connected, disconnected, chat_presence.
  • Convenção snake_case, formato de erro { error: { code, message } }, rate limit por instância.