Documentação da API

API REST para integrar o WhatsApp ao seu sistema: provisione números, envie e receba mensagens e mídias, e receba eventos por webhook.

Visão geral

Todas as requisições usam a base URL abaixo e retornam JSON. Há dois conjuntos de rotas: as da conta (provisionar/gerenciar números, autenticadas pela chave da conta) e as da instância (enviar/receber, no padrão de mercado, autenticadas pelo Client-Token).

Base URL

https://api.rexzap.rexsuite.com

Autenticação

Não há login por OAuth: cada conjunto de rotas usa um cabeçalho próprio.

Início rápido

Em quatro passos: provisione um número, mostre o QR, espere conectar e envie.

# 1) provisione um número (retorna id, token, clientToken e a URL do QR)
curl -X POST https://api.rexzap.rexsuite.com/provisionar \
  -H "X-RexZap-Account: SUA_CHAVE_DA_CONTA"

# 2) pegue o QR (data:image/png;base64,...) e exiba no seu sistema
curl https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/qr-code/image \
  -H "Client-Token: {clientToken}"

# 3) verifique a conexão até status = conectado
curl https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/status \
  -H "Client-Token: {clientToken}"

# 4) envie a primeira mensagem
curl -X POST https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/send-text \
  -H "Client-Token: {clientToken}" \
  -H "Content-Type: application/json" \
  -d '{"phone":"5544999999999","message":"olá 👋"}'

Provisionar números

Rotas da conta — header X-RexZap-Account. Seu sistema cria e gerencia números sem entrar no painel.

{
  "id": "34DEA54FF15492214CB8FAD5470C62F8",
  "token": "9E8937994C27C132E835A0680B194C21",
  "clientToken": "92912E057CE1...",
  "status": "desconectado",
  "qrCodeUrl": "/instances/{id}/token/{token}/qr-code/image",
  "statusUrl": "/instances/{id}/token/{token}/status"
}

[
  { "id": "...", "token": "...", "clientToken": "...",
    "numero": "5544999999999", "perfilNome": "Maria", "status": "conectado" }
]

{ "ok": true }

Cota

{ "used": 1, "limit": 10, "active": true, "status": "active" }

Enviar texto

Rotas de instância — path /instances/{id}/token/{token} + header Client-Token. A resposta de envio traz os ids da mensagem.

{ "zaapId": "...", "messageId": "...", "id": "..." }

Enviar imagem

{ "zaapId": "...", "messageId": "...", "id": "..." }

Enviar documento

{ "zaapId": "...", "messageId": "...", "id": "..." }

Enviar áudio

{ "zaapId": "...", "messageId": "...", "id": "..." }

Enviar vídeo

{ "zaapId": "...", "messageId": "...", "id": "..." }

Enviar link

Envia um texto com prévia de link (título, descrição e imagem do site quando disponível).

{ "zaapId": "...", "messageId": "...", "id": "..." }

curl -X POST https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/send-link \
  -H "Client-Token: {clientToken}" \
  -H "Content-Type: application/json" \
  -d '{"phone":"5544999999999","linkUrl":"https://rexzap.rexsuite.com","message":"Veja:","title":"RexZap","linkDescription":"API de WhatsApp"}'

Enviar localização

{ "zaapId": "...", "messageId": "...", "id": "..." }

Enviar contato

{ "zaapId": "...", "messageId": "...", "id": "..." }

Enviar figurinha

{ "zaapId": "...", "messageId": "...", "id": "..." }

Enviar GIF

{ "zaapId": "...", "messageId": "...", "id": "..." }

Reagir a mensagem

Envia uma reação (emoji) a uma mensagem existente. Passa pela fila como os demais envios.

{ "zaapId": "...", "messageId": "...", "id": "..." }

curl -X POST https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/send-reaction \
  -H "Client-Token: {clientToken}" \
  -H "Content-Type: application/json" \
  -d '{"phone":"5544999999999","messageId":"3EB0...","reaction":"👍"}'

Remover reação

Remove a reação previamente enviada a uma mensagem (envia uma reação vazia).

{ "zaapId": "...", "messageId": "...", "id": "..." }

Marcar como lida

Marca uma mensagem recebida como lida (os ticks azuis no aparelho do contato).

{ "value": true }

Apagar mensagem

Apaga uma mensagem para todos (deletar para todos). Os parâmetros vão na query string.

{ "value": true }

curl -X DELETE "https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/messages?messageId=3EB0...&phone=5544999999999&owner=true" \
  -H "Client-Token: {clientToken}"

Encaminhar mensagem

Encaminha uma mensagem existente para outro número. Passa pela fila como os demais envios.

{ "zaapId": "...", "messageId": "...", "id": "..." }

Botões de ação (beta)

Envia uma mensagem com botões de ação (abrir link, ligar ou resposta rápida). Passa pela fila como os demais envios.

{ "zaapId": "...", "messageId": "...", "id": "..." }

curl -X POST https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/send-button-actions \
  -H "Client-Token: {clientToken}" \
  -H "Content-Type: application/json" \
  -d '{"phone":"5544999999999","message":"Como podemos ajudar?","buttonActions":[{"type":"url","label":"Abrir site","url":"https://rexzap.rexsuite.com"},{"type":"reply","label":"Falar com humano"}]}'

Lista de botões (beta)

Envia uma mensagem com botões de resposta rápida (o contato toca um botão e a resposta volta como mensagem). Passa pela fila como os demais envios.

{ "zaapId": "...", "messageId": "...", "id": "..." }

curl -X POST https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/send-button-list \
  -H "Client-Token: {clientToken}" \
  -H "Content-Type: application/json" \
  -d '{"phone":"5544999999999","message":"Escolha uma opção:","buttonList":{"buttons":[{"id":"1","label":"Suporte"},{"id":"2","label":"Vendas"}]}}'

Lista de opções (beta)

Envia uma mensagem com um menu de lista (o contato abre a lista e escolhe uma opção). Passa pela fila como os demais envios.

{ "zaapId": "...", "messageId": "...", "id": "..." }

curl -X POST https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/send-option-list \
  -H "Client-Token: {clientToken}" \
  -H "Content-Type: application/json" \
  -d '{"phone":"5544999999999","message":"Escolha um setor:","optionList":{"title":"Setores","buttonLabel":"Ver opções","options":[{"id":"sup","title":"Suporte","description":"Ajuda técnica"},{"id":"ven","title":"Vendas"}]}}'

Listar fila

Mensagens ainda na fila de envio (aguardando o delay/aquecimento). Cada item traz o zaapId usado para remover.

[
  { "zaapId": "...", "phone": "5544999999999",
    "type": "text", "message": "olá 👋",
    "scheduled": "2024-06-10T12:00:00+00:00" }
]

curl https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/queue \
  -H "Client-Token: {clientToken}"

Limpar fila

{ "value": true }

Remover da fila

{ "value": true }

Status de texto

Publica um status (story) de texto no status@broadcast. Visível a todos os contatos que têm o número salvo. É síncrono (não passa pela fila): publica direto e os três campos da resposta trazem o MessageId real da publicação.

{ "zaapId": "...", "messageId": "...", "id": "..." }

Status de imagem

Publica um status (story) de imagem no status@broadcast. Visível a todos os contatos que têm o número salvo. É síncrono (não passa pela fila): publica direto e os três campos da resposta trazem o MessageId real da publicação.

{ "zaapId": "...", "messageId": "...", "id": "..." }

Número existe no WhatsApp

Verifica se um número tem conta no WhatsApp antes de enviar.

{ "exists": true, "phone": "5544999999999", "outputPhone": "5544999999999" }

curl https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/phone-exists/5544999999999 \
  -H "Client-Token: {clientToken}"

Foto de perfil

{ "link": "https://...whatsapp.net/...jpg" }
{ "link": null }

Listar contatos

Lista os contatos com quem o número já conversou. Não é a agenda inteira do aparelho — só quem trocou mensagens com esta instância. Paginado.

[
  { "phone": "5544999999999", "name": "Maria" }
]

curl "https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/contacts?page=1&pageSize=50" \
  -H "Client-Token: {clientToken}"

Dados do contato

{
  "phone": "5544999999999",
  "name": "Maria",
  "exists": true
}

Listar chats

Lista as conversas (chats) da instância — uma por número que já trocou mensagens. Mesma semântica de contatos: não inclui conversas sem histórico nesta instância. Paginado.

[
  { "phone": "5544999999999", "name": "Maria",
    "lastMessageText": "até amanhã", "lastMessageTime": 1718000000000,
    "unread": 0, "archived": false }
]

curl "https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/chats?page=1&pageSize=50" \
  -H "Client-Token: {clientToken}"

Mensagens do chat

Histórico de mensagens de uma conversa, da mais recente para a mais antiga. Use lastMessageId para paginar (cursor).

[
  { "phone": "5544999999999", "fromMe": false,
    "tipo": "text", "texto": "oi", "messageId": "3EB0...",
    "status": "RECEIVED", "momment": 1718000000000,
    "midiaUrl": null, "midiaMime": null, "midiaNome": null }
]

curl "https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/chat-messages/5544999999999?amount=20" \
  -H "Client-Token: {clientToken}"

Dados do chat

{
  "phone": "5544999999999",
  "name": "Maria",
  "lastMessageTime": 1718000000000,
  "messagesCount": 42
}

Modificar chat

Arquiva, desarquiva, marca como lida/não lida ou apaga uma conversa. A ação delete é destrutiva (apaga a conversa) — use com cuidado.

{ "value": true }

curl -X POST https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/modify-chat \
  -H "Client-Token: {clientToken}" \
  -H "Content-Type: application/json" \
  -d '{"phone":"5544999999999","action":"archive"}'

Criar grupo

Cria um grupo e adiciona os participantes informados. O número conectado entra como administrador. Os grupos usam id@g.us; nas rotas de grupo seguintes, envie esse id no campo groupId (com o sufixo @g.us, como retornado aqui).

{ "groupId": "120363000000000000@g.us", "invitationLink": null }

curl -X POST https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/create-group \
  -H "Client-Token: {clientToken}" \
  -H "Content-Type: application/json" \
  -d '{"groupName":"Equipe RexZap","phones":["5544999999999","5544988888888"]}'

Alterar nome do grupo

{ "value": true }

Alterar foto do grupo

{ "value": true }

Alterar descrição do grupo

{ "value": true }

Configurações do grupo

Controla quem pode enviar mensagens e quem pode editar os dados do grupo (nome, foto, descrição). Requer administrador.

{ "value": true }

Adicionar participante

{ "value": true }

Remover participante

{ "value": true }

Promover a admin

{ "value": true }

Rebaixar admin

{ "value": true }

Sair do grupo

{ "value": true }

Dados do grupo

Retorna os metadados do grupo: nome, descrição, dono, participantes e quem é administrador.

{
  "phone": "120363000000000000",
  "subject": "Equipe RexZap",
  "description": "Grupo da equipe",
  "owner": "5544999999999",
  "participants": [
    { "phone": "5544999999999", "isAdmin": true, "isSuperAdmin": true },
    { "phone": "5544988888888", "isAdmin": false, "isSuperAdmin": false }
  ]
}

Dados por convite

Lê os metadados de um grupo a partir do link de convite, sem precisar fazer parte dele.

{
  "phone": "120363000000000000",
  "subject": "Equipe RexZap",
  "description": "Grupo da equipe",
  "owner": "5544999999999",
  "participants": [
    { "phone": "5544999999999", "isAdmin": true, "isSuperAdmin": true }
  ]
}

curl "https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/group-invitation-metadata?url=https://chat.whatsapp.com/ABC123" \
  -H "Client-Token: {clientToken}"

Status

{ "connected": true, "session": true, "error": "", "smartphoneConnected": true }
{ "connected": false, "session": false, "error": "You are not connected.", "smartphoneConnected": false }

Dados do aparelho

{
  "phone": "5544999999999", "imgUrl": null,
  "device": { "wa_version": "", "mcc": "", "mnc": "",
    "os_version": "", "device_manufacturer": "", "device_model": "",
    "osbuildnumber": "", "platform": "" }
}

Alterar nome do perfil

Altera o nome de exibição (perfil) do número conectado.

{ "value": true }

curl -X PUT https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/update-name \
  -H "Client-Token: {clientToken}" \
  -H "Content-Type: application/json" \
  -d '{"value":"Atendimento RexZap"}'

Alterar foto do perfil

Altera a foto de perfil do número conectado. Aplicação é best-effort: o WhatsApp pode recusar a imagem (formato/tamanho) e a foto pode não trocar mesmo com resposta de sucesso.

{ "value": true }

Leitura automática

Liga/desliga a marcação automática como lida das mensagens recebidas (ticks azuis).

{ "value": true }

Rejeitar chamadas

Liga/desliga a rejeição automática de chamadas recebidas (voz e vídeo). A rejeição é best-effort: depende do comportamento do WhatsApp e pode variar.

{ "value": true }

Mensagem de chamada rejeitada

Define o texto enviado automaticamente ao contato quando uma chamada é rejeitada (requer a rejeição automática ligada).

{ "value": true }

QR Code

{ "value": "data:image/png;base64,iVBORw0KG..." }
{ "value": null }

QR Code (texto)

{ "value": "data:image/png;base64,iVBORw0KG..." }
{ "value": null }

curl https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/qr-code \
  -H "Client-Token: {clientToken}"

Restaurar sessão

{ "value": true }

Reiniciar / Desconectar

{ "value": true }

{ "value": true }

Configurar webhooks

Defina as URLs que receberão os eventos. Rotas PUT de instância, body { "value": "https://sua-app/webhook" }.

Webhook ao enviar

{ "value": true }

Webhook de presença

{ "value": true }

Eventos recebidos

O RexZap faz POST na sua URL com estes formatos.

Mensagem de texto

Todo ReceivedCallback traz os campos de topo abaixo e mais um objeto conforme o tipo da mensagem. senderLid é o @lid do remetente (quando houver). senderPhoto e photo vêm null no momento.

{
  "waitingMessage": false, "isGroup": false,
  "instanceId": "...", "messageId": "...",
  "phone": "5544999999999", "senderLid": null, "fromMe": false,
  "momment": 1718000000000, "status": "RECEIVED",
  "chatName": "Maria", "senderPhoto": null, "senderName": "Maria",
  "participantPhone": null, "photo": null, "broadcast": false,
  "type": "ReceivedCallback",
  "text": { "message": "olá" }
}

Mídia (imagem, áudio, vídeo, documento, sticker)

Mesma estrutura, com um objeto por tipo. A URL é um link estável do RexZap (o arquivo fica em armazenamento privado).

{
  "type": "ReceivedCallback", "status": "RECEIVED", "instanceId": "...",
  "phone": "...", "fromMe": false, "momment": 1718000000000, "broadcast": false,
  "image":    { "imageUrl": "https://api.rexzap.rexsuite.com/media/...", "caption": "...", "mimeType": "image/jpeg" },
  "audio":    { "audioUrl": "...", "mimeType": "audio/ogg" },
  "video":    { "videoUrl": "...", "caption": "...", "mimeType": "video/mp4" },
  "document": { "documentUrl": "...", "mimeType": "application/pdf", "fileName": "nota.pdf" },
  "sticker":  { "stickerUrl": "...", "mimeType": "image/webp" }
}

Reação

Quando reagem a uma mensagem. referencedMessage aponta a mensagem reagida.

{
  "type": "ReceivedCallback", "status": "RECEIVED", "instanceId": "...", "messageId": "...",
  "phone": "...", "fromMe": false, "momment": 1718000000000,
  "reaction": {
    "value": "❤️", "time": 1718000000000,
    "referencedMessage": { "messageId": "3EB0...", "fromMe": true, "phone": "5544999999999", "participant": null }
  }
}

Localização

{ "type": "ReceivedCallback", "instanceId": "...", "phone": "...", "fromMe": false,
  "location": { "longitude": -38.5014, "latitude": -3.7319, "address": "Rua X, 123", "url": "" } }

Contato

{ "type": "ReceivedCallback", "instanceId": "...", "phone": "...", "fromMe": false,
  "contact": { "displayName": "Cesar", "vCard": "BEGIN:VCARD...END:VCARD", "phones": ["5544999999999"] } }

Resposta de botão / lista

Quando o contato clica num botão ou seleciona um item de lista.

{ ..., "buttonsResponseMessage": { "buttonId": "1", "message": "Ótimo" } }
{ ..., "listResponseMessage": { "message": "...", "title": "...", "selectedRowId": "1" } }

Status / conexão

{ "type": "MessageStatusCallback", "instanceId": "...", "status": "SENT", "ids": ["<id real>"], "zaapId": "<id da fila>", "phone": "...", "momment": 1718000000000 }
{ "type": "ConnectedCallback", "instanceId": "...", "momment": 1718000000000 }
{ "type": "DisconnectedCallback", "instanceId": "...", "momment": 1718000000000 }

Ao enviar (DeliveryCallback)

Disparado quando o próprio número envia uma mensagem (saída da fila), na URL de /update-webhook-delivery.

{
  "type": "DeliveryCallback",
  "instanceId": "...", "messageId": "<id real>", "zaapId": "<id da fila>",
  "phone": "5544999999999",
  "momment": 1718000000000
}

Presença no chat (ChatPresenceCallback)

Disparado quando muda a presença de um contato no chat, na URL de /update-webhook-chat-presence. O campo status assume composing (digitando), recording (gravando áudio), available (online), unavailable (offline) ou paused (parou de digitar).

{
  "type": "ChatPresenceCallback", "instanceId": "...",
  "phone": "5544999999999",
  "status": "composing",
  "momment": 1718000000000
}

Criar produto

Cria um produto no catálogo do número conectado (conta Business).

{ "id": "7100...", "name": "Camiseta RexZap", "currency": "BRL", "isHidden": false }

curl -X POST https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/products \
  -H "Client-Token: {clientToken}" \
  -H "Content-Type: application/json" \
  -d '{"name":"Camiseta RexZap","price":59.9,"currency":"BRL"}'

Catálogo próprio

Lista os produtos do catálogo do número conectado (conta Business).

{
  "products": [
    { "id": "7100...", "name": "Camiseta RexZap", "currency": "BRL" }
  ]
}

curl https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/catalogs \
  -H "Client-Token: {clientToken}"

Catálogo de um número

Lista os produtos do catálogo de outro número (conta Business).

{
  "products": [
    { "id": "7100...", "name": "Camiseta", "currency": "BRL" }
  ]
}

Dados do produto

{
  "id": "7100...",
  "name": "Camiseta RexZap",
  "currency": "BRL",
  "description": "...",
  "isHidden": false
}

Excluir produto

{ "value": true }

Listar etiquetas

Lista as etiquetas (tags) da conta. Só WhatsApp Business Multi-Devices.

[
  { "id": "1", "name": "Novo cliente", "color": 0 }
]

curl https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/tags \
  -H "Client-Token: {clientToken}"

Adicionar etiqueta ao chat

Aplica uma etiqueta a uma conversa. Só WhatsApp Business Multi-Devices.

{ "value": true }

curl -X PUT https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/chats/5544999999999/tags/1/add \
  -H "Client-Token: {clientToken}"

Remover etiqueta do chat

Remove uma etiqueta de uma conversa. Só WhatsApp Business Multi-Devices. Por compatibilidade com a PlugzAPI, esta rota usa o método GET.

{ "value": true }

curl https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/chats/5544999999999/tags/1/remove \
  -H "Client-Token: {clientToken}"

Erros

Todo erro vem como JSON { "error": "motivo" } com o status HTTP correspondente. Antes de qualquer send-*, o número precisa estar com status conectado; caso contrário a resposta é 400 { "error": "disconnected" }.