https://api.wabox.me — o formato da rota é o mesmo: /instances/{instance_id}/token/{token}/....
Body e response são em snake_case (o z-api usa camelCase); veja a lista de campos renomeados no fim da página.
O header Client-Token funciona igual, quando ativado no workspace.
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; 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, connected_url, disconnected_url, 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 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 | — | — | 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; 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 | — | — | 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-* | — | — | 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 | — | — | 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 | — | — | 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 | — | — | 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
Ids de grupo no 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 | — | Publicar no canal = qualquer send-* com phone: "<id>@newsletter". |
broadcast/* | — | — | 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 — dados vêm do bloco order do webhook received. GET /business/orders/{id}?token= lê os itens. |
POST /order-payment-update | — | — | 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 | — | — | API de partner ainda não está disponível; está planejada como /partner/* com Authorization: Bearer <partner_token>. Enquanto isso, instâncias são criadas no painel e o proxy é por instância em PUT /settings { "proxy_url" }. |
calls (send-call, SDK, SIP) | — | — | Sem chamadas de voz/vídeo no WhatsApp Web. |
mobile (/mobile/*) | — | — | Registrar o número como aparelho principal está fora de escopo; o Wabox é sempre um aparelho vinculado. |
| Meta AI | — | — | Não exposto pelo protocolo do WhatsApp Web. |
| MCP server (Apps conectados) | — | — | Ainda não disponível. |
Campos renomeados
O z-api usacamelCase; o Wabox usa snake_case em tudo. 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 → snake_case e confira o nome final na API Reference. Os payloads completos estão em Webhook received.