Migrando do z-api

O Wabox foi desenhado para que quem vem da z-api mude o mínimo possível: o mesmo formato de rota, os mesmos conceitos (instância, token, Client-Token, webhooks por tipo, fila) e os mesmos nomes de endpoint na maioria dos casos. A diferença principal é a convenção de nomes: snake_case em tudo.

O que não muda

Rota: /instances/{instance_id}/token/{token}/<endpoint> — só o host passa a ser api.wabox.me.
Header Client-Token, com o mesmo papel.
Webhooks por tipo (received, delivery, message_status, connected, disconnected, chat_presence) com o campo momment mantido de propósito.
Envio assíncrono: resposta imediata com id, resultado no delivery.
Os nomes da maioria dos endpoints: send-text, send-image, send-button-list, send-option-list, send-carousel, qr-code, status, phone-exists, queue…
Vários endpoints da z-api continuam funcionando como alias (/create-group, /profile-picture, /modify-chat, /tags, /send-button-actions…). Veja a coluna “Alias aceito” na tabela de rotas.

O que muda

Nomes de campos
Mídia
Webhooks
Erros
O que não existe

camelCase → snake_case. Os mais usados:

z-api	Wabox
`messageId` (ao responder)	`reply_to_message_id`
`messageId` (na resposta do envio)	`message_id` (e `id` como alias)
`zaapId`	`wabox_id`
`delayMessage`, `delayTyping`	`delay_message`, `delay_typing`
`editMessageId`	`edit_message_id`
`mentionAll`	`mention_all`
`isGroup`, `fromMe`, `fromApi`	`is_group`, `from_me`, `from_api`
`senderName`, `chatName`	`sender_name`, `chat_name`
`referenceMessageId`	`reference_message_id`
`image.imageUrl`	`image.url`
`notifySentByMe`	`notify_sent_by_me`

A lista completa está na tabela de rotas.

O campo de mídia tem o nome do tipo (image, audio, document…) e aceita URL, data: URL ou base64 puro. send-document/{extension} funciona, mas extension também pode ir no body.

Configuração num objeto só: PUT /webhooks com todas as URLs e filtros (em vez de um endpoint por URL). PUT /webhooks/{type} com { "value": "..." } também existe.
Assinatura HMAC em X-Wabox-Signature — verifique, é de graça. Veja Assinatura dos webhooks.
event_id único por entrega para deduplicar.
Conteúdo de mídia recebida em image.url (assinada, 24 h) em vez de imageUrl.

Sempre { "error": { "code", "message" } }, com code estável. Veja Erros.

Chamadas (send-call), instâncias mobile, listas de transmissão, Meta AI, order-payment-update, reply-button/reply-template-button (no Wabox as respostas chegam pelo webhook, não são endpoints) e a API Partner. Detalhes e motivos em Limitações conhecidas.

Migrando sem parar

Crie a instância no Wabox e conecte o número

Um número só pode estar vinculado a uma sessão web por provedor, mas pode ter vários aparelhos vinculados. Você pode conectar o mesmo número no Wabox enquanto a z-api ainda está ativa e comparar os webhooks lado a lado.

Aponte os webhooks para um endpoint novo

Faça o seu handler aceitar os dois formatos (ou converta o payload do Wabox para o formato antigo com um adaptador de 20 linhas). Compare por alguns dias.

Troque os envios

Mude o host e os nomes de campos. Se você usa alguma biblioteca ou nó no-code apontando para a z-api, o HTTP genérico resolve.

Desligue a instância antiga

Remova o aparelho da z-api em Aparelhos conectados no celular. Duas sessões ativas no mesmo número dividem os eventos recebidos entre si sem problema, mas não faz sentido pagar duas.

Adaptador de payload (exemplo)

Se você quer trocar o host hoje e mexer no código depois:

// Converte um webhook `received` do Wabox para o formato camelCase antigo (subconjunto)
export function toLegacy(event) {
  return {
    type: "ReceivedCallback",
    instanceId: event.instance_id,
    messageId: event.message_id,
    phone: event.phone,
    fromMe: event.from_me,
    fromApi: event.from_api,
    isGroup: event.is_group,
    chatName: event.chat_name,
    senderName: event.sender_name,
    momment: event.momment,
    referenceMessageId: event.reference_message_id,
    text: event.text ? { message: event.text.message } : undefined,
    image: event.image ? { imageUrl: event.image.url, caption: event.image.caption, mimeType: event.image.mime_type } : undefined,
    // ...outros tipos conforme o seu uso
  };
}

Trate isso como ponte temporária: o formato do Wabox é o que evolui e ganha campos novos.

Começar

Autenticação e segurança

Webhooks

Guias

Migrando do z-api

Integrações

Partner

Referências

Migrando do z-api

O que não muda

O que muda

Migrando sem parar

Adaptador de payload (exemplo)

​O que não muda

​O que muda

​Migrando sem parar

​Adaptador de payload (exemplo)

O que não muda

O que muda

Migrando sem parar

Adaptador de payload (exemplo)