https://api.wabox.me. O formato da rota é o mesmo, /instances/{instance_id}/token/{token}/....
Body e response usam snake_case (o z-api usa camelCase). A lista de campos renomeados está no fim da página.
O header Client-Token continua aceito. O valor passa a ser uma API key do Wabox com a permissão instances:operate, exigida só quando o workspace liga “Exigir API key nas rotas de instância” (veja Migrando do z-api).
Os caminhos abaixo omitem o prefixo /instances/{instance_id}/token/{token}. A coluna “Alias aceito” lista as rotas no formato z-api que o Wabox ainda atende. Elas não aparecem na API Reference e podem sair no futuro, então migre para a rota Wabox quando puder.
Instância
| z-api | Wabox | Alias aceito | Observação |
|---|---|---|---|
GET /qr-code | GET /qr-code | Resposta { "value": "data:image/png;base64,…" }. | |
GET /qr-code/image | GET /qr-code/image | PNG puro. | |
GET /phone-code/{phone} | GET /phone-code/{phone} | Código de pareamento por número. | |
GET /status | GET /status | { connected, smartphone_connected, status, phone, error }. | |
GET /me | GET /me | Inclui settings, webhooks e api_url. | |
GET /device | GET /device | ||
GET /restart | POST /restart | Só POST; GET /restart não funciona. | |
GET /disconnect | POST /disconnect | Só POST; GET /disconnect não funciona. Faz logout do WhatsApp (novo QR depois). | |
PUT /update-name | PUT /name | Body { "value": "..." }. PUT /update-name não funciona. | |
PUT /update-webhook-*, PUT /update-every-webhooks, PUT /update-notify-sent-by-me, PUT /update-filters | PUT /webhooks (parcial) ou PUT /webhooks/{type} { "value": url } | Um objeto só: received_url, delivery_url, message_status_url, instance_status_url (substitui os webhooks de conexão/desconexão do z-api: um evento por mudança de status, com phone e disconnect_reason), chat_presence_url, notify_sent_by_me, ignore_*. GET /webhooks lê tudo, incluindo o secret de assinatura. | |
PUT /update-auto-read-message, PUT /update-auto-read-status, PUT /update-call-reject-auto, PUT /update-call-reject-message, PUT /update-queue-settings | PUT /settings (parcial) | auto_read_message, auto_read_status, call_reject_auto, call_reject_message, disable_enqueue_when_disconnected. GET /settings lê. | |
PUT /profile-name | PUT /profile/name | PUT /profile-name | Body { "value": "..." }. |
PUT /profile-description | PUT /profile/about | PUT /profile-description | Body { "value": "..." }. |
PUT /profile-picture | PUT /profile/picture | PUT /profile-picture | URL, data URL ou base64. DELETE /profile/picture remove a foto. |
passkey-prologue, reset-passkey-challenge, extension-token | Sem equivalente | Sem suporte no protocolo que usamos (whatsmeow); reavaliado quando existir. |
Envio de mensagens
Todas as rotas de envio respondem{ "id", "message_id", "wabox_id", "status": "queued" } e o resultado chega no webhook delivery.
| z-api | Wabox | Alias aceito | Observação |
|---|---|---|---|
POST /send-text | POST /send-text | Reply com reply_to_message_id; edição com edit_message_id; mentioned / mention_all; delay_message / delay_typing. | |
POST /send-image | POST /send-image | image aceita URL, data URL ou base64; caption, view_once. | |
POST /send-audio | POST /send-audio | audio + ptt (voice note) e waveform. | |
POST /send-video | POST /send-video | ||
POST /send-ptv | POST /send-ptv | Vídeo redondo (nota de vídeo). | |
POST /send-gif | POST /send-gif | MP4 com reprodução de GIF. | |
POST /send-document/{extension} | POST /send-document | POST /send-document/{extension} | Na rota Wabox a extensão vai no body (extension) ou é inferida de mime_type / file_name. |
POST /send-sticker | POST /send-sticker | ||
POST /send-location | POST /send-location | latitude, longitude, name, address, url. | |
POST /send-contact | POST /send-contact | contact_name, contact_phone, contact_description (ou vcard). | |
POST /send-contacts | POST /send-contacts | Vários cartões em uma mensagem. | |
POST /send-link | POST /send-link | url, title, description, image vêm de você (sem scraping). | |
POST /send-reaction | POST /send-reaction | message_id, reaction. | |
POST /send-remove-reaction | POST /remove-reaction | Nome mudou. | |
POST /forward-message | POST /forward-message | message_id, from_phone. | |
POST /pin-message | POST /pin-message | pin: true/false, duration_seconds. | |
POST /read-message | POST /read-message | message_id ou message_ids[]. | |
DELETE /messages | DELETE /messages | Query phone, message_id, owner (false para apagar de outro como admin do grupo). | |
POST /send-poll | POST /send-poll | question, options, poll_max_options. | |
POST /send-poll-vote | POST /send-poll-vote | poll_message_id, options. | |
POST /send-call | Sem equivalente | O WhatsApp Web (whatsmeow) não faz chamadas de saída. Você pode rejeitar chamadas recebidas com call_reject_auto + call_reject_message em PUT /settings. |
Interativos
Botões, listas e carrossel são best effort. Renderizam no celular, e no WhatsApp Web/Desktop aparece um placeholder. Veja O que renderiza onde.| z-api | Wabox | Alias aceito | Observação |
|---|---|---|---|
POST /send-button-list | POST /send-button-list | Botões reply, url, call e copy no mesmo endpoint. | |
POST /send-button-actions | POST /send-button-list | POST /send-button-actions | Mesmo endpoint dos botões de resposta. |
POST /send-option-list | POST /send-option-list | button_label, sections (ou options). | |
POST /send-button-otp | POST /send-button-otp | code + botão de copiar. | |
POST /send-button-pix | POST /send-button-pix | key, key_type (cpf, cnpj, phone, email, evp), name. | |
POST /send-carousel | POST /send-carousel | cards[] com imagem, texto e até 3 botões. | |
POST /reply-button, POST /reply-template-button | Sem equivalente | São respostas do destinatário, não envios. Chegam no webhook received como buttons_response / list_response. | |
POST /send-event | POST /send-event | name, start_at, end_at, location, join_link. | |
POST /send-edit-event | POST /send-edit-event | Só eventos que o engine viu (o segredo do evento é necessário). | |
POST /send-event-response | POST /send-event-response | RSVP; chega no received como event_response. | |
POST /send-text-status | POST /send-text-status | Sem phone; background_color, font. | |
POST /send-image-status | POST /send-image-status | Sem phone. | |
POST /send-video-status | POST /send-video-status | Sem phone. | |
POST /reply-status-* | Sem equivalente | Não implementado. | |
POST /send-newsletter-admin-invite | POST /send-newsletter-admin-invite | newsletter_id, caption. Para publicar num canal, use qualquer send-* com phone: "<id>@newsletter". |
Chats, contatos e privacidade
| z-api | Wabox | Alias aceito | Observação |
|---|---|---|---|
GET /chats | GET /chats | ||
GET /chats/{phone} | GET /chats/{phone} | ||
POST /modify-chat | POST /chats/{phone}/{action} | POST /modify-chat | action ∈ archive, unarchive, mute, unmute, pin, unpin, read, unread, delete. Para mute, body { "mute_seconds": 28800 }. No alias, phone e action vão no body. |
POST /send-chat-expiration | PUT /chats/{phone}/expiration | Body { "value": 0 | 86400 | 604800 | 7776000 } (segundos; 0 desliga). | |
chats/{phone}/notes | Sem equivalente | Ainda não implementado. | |
chats/{phone}/tags/{id}/add, .../remove | PUT /chats/{phone}/labels/{id}, DELETE /chats/{phone}/labels/{id} | PUT /chats/{phone}/tags/{id}/add, DELETE /chats/{phone}/tags/{id}/remove | Só contas WhatsApp Business. Ver Business e etiquetas. |
GET /contacts | GET /contacts | ||
GET /contacts/{phone} | GET /contacts/{phone} | ||
GET /profile-picture | GET /contacts/{phone}/picture | GET /profile-picture?phone= | ?preview=true para a miniatura. Serve para usuário ou grupo. |
GET /phone-exists/{phone} | GET /phone-exists/{phone} | ||
POST /phone-exists-batch | POST /phone-exists-batch | Body { "phones": [...] }, até 50. | |
POST /contacts/add, POST /contacts/remove | Sem equivalente | Ainda não implementado (a agenda fica no aparelho). | |
PUT /modify-blocked | POST /contacts/{phone}/block, POST /contacts/{phone}/unblock | PUT /modify-blocked | No alias, body { "phone", "action": "block" | "unblock" }. GET /contacts/blocked lista os bloqueados. |
POST /report | Sem equivalente | Não implementado. | |
privacy/* | GET /privacy, PUT /privacy/{setting} | setting ∈ last_seen, online, profile_picture, about, read_receipts, groups, calls, messages, stickers, disappearing. Body { "value": "..." }. | |
presença (delayTyping nos envios) | POST /send-presence | { "phone", "status": "composing" | "recording" | "paused" }. Os envios continuam aceitando delay_typing. |
Grupos, comunidades e canais
Os ids de grupo têm o formato<id>-group (o JID <id>@g.us também é aceito).
| z-api | Wabox | Alias aceito | Observação |
|---|---|---|---|
POST /create-group | POST /groups | POST /create-group | |
GET /groups | GET /groups | ||
GET /group-metadata/{id}, GET /light-group-metadata/{id} | GET /groups/{id} | Uma rota só, já com participantes. | |
GET /group-invitation-metadata | GET /groups/invite-info?url= | GET /group-invitation-metadata | |
POST /accept-invite-group | POST /groups/join | POST /accept-invite-group | |
GET /group-invitation-link/{id} | GET /groups/{id}/invite-link | ||
POST /redefine-invitation-link/{id} | POST /groups/{id}/invite-link/revoke | Revoga e devolve o novo link. | |
POST /add-participant, POST /remove-participant | POST /groups/{id}/participants | POST /groups/{id}/add-participant, POST /groups/{id}/remove-participant | Body { "action": "add" | "remove", "phones": [...] }; nos aliases só { "phones": [...] }. Resultado por telefone. |
POST /add-admin, POST /remove-admin | POST /groups/{id}/participants | POST /groups/{id}/add-admin, POST /groups/{id}/remove-admin | action ∈ promote, demote. |
POST /approve-participant, POST /reject-participant | POST /groups/{id}/participants | action ∈ approve, reject. Pendentes em GET /groups/{id}/requests. | |
POST /leave-group | POST /groups/{id}/leave | ||
PUT /update-group-name, PUT /update-group-description, PUT /update-group-photo, PUT /update-group-settings | PUT /groups/{id} (parcial) | name, description, picture (remove_picture: true limpa), announce, locked, join_approval_required, member_add_mode, ephemeral_seconds. | |
communities/* | POST /communities, GET /communities, GET /communities/{id}, PUT /communities/{id}, GET /communities/{id}/participants, POST /communities/{id}/groups (vincular), POST /communities/{id}/groups/create, POST /communities/{id}/groups/unlink, DELETE /communities/{id}/groups/{group_id}, POST /communities/{id}/leave | Vincular/desvincular recebe { "group_ids": [...] }. | |
newsletter/* | POST /newsletters, GET /newsletters, GET /newsletters/invite-info?invite=, GET /newsletters/{id}, POST /newsletters/{id}/follow, .../unfollow, .../mute, .../unmute, GET /newsletters/{id}/messages, POST /newsletters/{id}/reaction, POST /newsletters/{id}/read | Para publicar no canal, use qualquer send-* com phone: "<id>@newsletter". | |
broadcast/* | Sem equivalente | O WhatsApp Web não cria nem envia para listas de transmissão. Só status@broadcast (status) funciona. |
Fila
| z-api | Wabox | Alias aceito | Observação |
|---|---|---|---|
POST /queue (listar) | GET /queue | Virou GET. | |
DELETE /queue | DELETE /queue | Limpa a fila inteira. | |
DELETE /queue/{zaapId} | DELETE /queue/{wabox_id} | wabox_id vem da resposta do envio. | |
PUT /update-queue-settings | PUT /settings | { "disable_enqueue_when_disconnected": true }. |
Business e etiquetas
Rotas de catálogo e pedidos são best effort (IQw:biz / w:biz:catalog do WhatsApp Web). Etiquetas existem só em contas WhatsApp Business.
| z-api | Wabox | Alias aceito | Observação |
|---|---|---|---|
business/profile | GET /business/profile, PUT /business/profile | ?phone= lê o perfil de outro negócio. | |
| categorias, horários | PUT /business/profile | Campos categories e business_hours do mesmo body (com description, address, email, website). | |
| products | GET /business/products, POST /business/products, PUT /business/products/{id}, DELETE /business/products/{id}, DELETE /business/products (lote) | ||
| catalogs, collections | GET /business/collections | O catálogo é a lista de produtos; coleções são só leitura. | |
POST /send-product | POST /send-product | product_id (id do WhatsApp ou seu retailer_id), business_phone para catálogo de terceiros. | |
POST /send-catalog | POST /send-catalog | Envia o link wa.me/c/<business_phone>. | |
POST /send-order | POST /send-order | title, item_count, total, currency. | |
POST /order-status-update | POST /order-status-update | order_id, token, order_request_message_id, status. Os dados vêm do bloco order do webhook received. GET /business/orders/{id}?token= lê os itens. | |
POST /order-payment-update | Sem equivalente | Sem suporte no whatsmeow. | |
GET /tags, POST /tags | GET /labels, POST /labels | GET /tags, POST /tags | POST recebe { "name", "color" } (color = índice 0–19). |
PUT /tags/{id}, DELETE /tags/{id} | PUT /labels/{id}, DELETE /labels/{id} | PUT /tags/{id}, DELETE /tags/{id} | |
PUT /chats/{phone}/tags/{id}/add, DELETE /chats/{phone}/tags/{id}/remove | PUT /chats/{phone}/labels/{id}, DELETE /chats/{phone}/labels/{id} | PUT /chats/{phone}/tags/{id}/add, DELETE /chats/{phone}/tags/{id}/remove | phone pode ser usuário ou grupo. |
Partner e outros
| z-api | Wabox | Alias aceito | Observação |
|---|---|---|---|
Partner: POST /instances/integrator/on-demand, subscription/cancel, GET /instances, configure-proxy, sdk-connector-token | /account/instances | Criar, listar, atualizar e excluir instâncias por API com uma API key do workspace (Authorization: Bearer) (contas com plano, até o número de slots). Não há subscription/cancel por instância. O plano é da conta e é cobrado por slot. Proxy é por instância em PUT /settings { "proxy_url" }. | |
calls (send-call, SDK, SIP) | Sem equivalente | Sem chamadas de voz/vídeo no WhatsApp Web. | |
mobile (/mobile/*) | Sem equivalente | Registrar o número como aparelho principal está fora de escopo; o Wabox é sempre um aparelho vinculado. | |
| Meta AI | Sem equivalente | Não exposto pelo protocolo do WhatsApp Web. | |
| MCP server (Apps conectados) | Sem equivalente | Ainda não disponível. |
Campos renomeados
O z-api usacamelCase e o Wabox usa snake_case em tudo. A tabela traz os que mais aparecem em código de integração.
| z-api | Wabox | Onde |
|---|---|---|
messageId (ao responder) | reply_to_message_id | body dos send-* |
messageId (na resposta do envio) | message_id | resposta dos send-* (id é alias, como no z-api) |
zaapId | wabox_id | resposta dos send-*, webhook delivery, DELETE /queue/{wabox_id} |
delayTyping | delay_typing | body dos send-* |
delayMessage | delay_message | body dos send-* |
editMessageId | edit_message_id | send-text, send-image, send-document |
mentioned / mentionAll | mentioned / mention_all | body dos send-* |
momment | momment (mantido) | webhooks (epoch em milissegundos) |
phone | phone (mantido) | body, resposta e webhooks |
isGroup | is_group | webhooks received, message_status |
fromMe | from_me | webhook received |
fromApi | from_api | webhook received |
senderName | sender_name | webhook received |
chatName | chat_name | webhook received |
referenceMessageId | reference_message_id | webhook received |
image.imageUrl | image.url | webhook received (o mesmo vale para audio, video, document, sticker) |
notifySentByMe | notify_sent_by_me | PUT /webhooks, GET /webhooks |
camelCase para snake_case e confira o nome final na API Reference. Os payloads completos estão em Webhook received.