Documentação da API

Visão geral

Toda operação de um número acontece dentro de uma instância. Cada instância tem um instanceId e um token, ambos no caminho da URL. O cabeçalho opcional Client-Token adiciona uma camada de segurança em nível de conta.

Uma instância equivale a um número de WhatsApp conectado. Elas são isoladas entre si: token, webhook e sessão são independentes.

Autenticação

Credencial	Onde vai	Quando
`instanceId` + `token`	Caminho da URL	Toda rota de instância. Identificam e autorizam.
`Client-Token`	Header HTTP	Opcional. Se definido na instância, passa a ser obrigatório em toda requisição.
`Authorization: Bearer`	Header HTTP	Apenas nas rotas administrativas `/admin/*`.

URL base

https://api.zapbot.online/instances/{instanceId}/token/{token}/{rota}

Migrando de outro provedor? Troque só o domínio na URL base. Corpo, headers e respostas permanecem idênticos — nenhuma linha da sua integração muda.

Erros

Respostas de erro trazem o código HTTP e um corpo JSON com a descrição.

Código	Significado
`400`	Corpo inválido ou campo obrigatório ausente.
`401`	Credencial inválida: token, `Client-Token` ou Bearer administrativo.
`404`	Instância inexistente.
`202`	QR Code ainda não pronto — repita a chamada em instantes.
`409`	Instância já conectada (ao pedir QR Code).

Criar instância

POST /admin/instances

Requer Authorization: Bearer <ADMIN_TOKEN>.

Campo	Tipo	Descrição
`name`	string	Rótulo da instância no painel.
`webhookUrl`	string	URL que recebe os eventos de entrada.
`clientToken`	string	Opcional. Se preenchido, vira obrigatório no header de toda chamada.

request

{
  "name": "Vendas",
  "webhookUrl": "https://seu-app.com/webhook",
  "clientToken": "opcional-token-de-seguranca"
}

201 created

{
  "id": "b1a2c3d4-...",
  "token": "f9e8d7c6-...",
  "clientToken": "opcional-token-de-seguranca",
  "name": "Vendas",
  "webhookUrl": "https://seu-app.com/webhook",
  "apiBaseUrl": "https://api.zapbot.online/instances/b1a2.../token/f9e8..."
}

Listar instâncias

GET /admin/instances

Retorna todas as instâncias com o status de conexão atual e o telefone conectado.

Deletar instância

DELETE /admin/instances/{id}

Desconecta o número e remove a instância. A operação não é reversível.

Status da conexão

GET /instances/{id}/token/{token}/status

200 ok

{
  "connected": true,
  "session": true,
  "smartphoneConnected": true,
  "phone": "5511777777777"
}

QR Code

GET /instances/{id}/token/{token}/qr-code/image

Inicia o pareamento e devolve o QR Code como PNG em base64. Escaneie em WhatsApp › Aparelhos conectados.

A primeira chamada apenas dispara o pareamento e pode responder 202. O código chega na chamada seguinte, poucos segundos depois.

200 ok

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

Variantes: GET /qr-code devolve o conteúdo bruto do código em value; GET /restart força a reconexão.

Desconectar

GET /instances/{id}/token/{token}/disconnect

Encerra a sessão do número. A instância continua existindo e pode ser pareada de novo.

Configurar webhook

PUT /instances/{id}/token/{token}/update-every-webhooks

request

{
  "value": "https://seu-app.com/webhook",
  "notifySentByMe": true
}

Enviar texto

POST /instances/{id}/token/{token}/send-text

Campo	Tipo	Descrição
`phone`obrigatório	string	Número com código do país, só dígitos.
`message`obrigatório	string	Texto da mensagem.

curl

curl -X POST "https://api.zapbot.online/instances/{id}/token/{token}/send-text" \
  -H "Content-Type: application/json" \
  -H "Client-Token: seu-token-de-seguranca" \
  -d '{"phone":"5511999999999","message":"Olá!"}'

200 ok — resposta padrão de todo send-*

{
  "zaapId": "3999984CE2CF9E0",
  "messageId": "3EB0C9A1F2D4",
  "id": "3EB0C9A1F2D4"
}

Guarde o messageId: é ele que identifica a mensagem nos webhooks de status e em send-reaction.

Enviar imagem

POST /instances/{id}/token/{token}/send-image

Campo	Tipo	Descrição
`phone`obrigatório	string	Destinatário.
`image`obrigatório	string	URL `http(s)` ou data URI base64 (`data:image/png;base64,...`).
`caption`	string	Legenda opcional.

request

{
  "phone": "5511999999999",
  "image": "https://exemplo.com/foto.jpg",
  "caption": "legenda opcional"
}

Enviar áudio

POST /instances/{id}/token/{token}/send-audio

Entregue como mensagem de voz no aparelho do destinatário.

request

{
  "phone": "5511999999999",
  "audio": "https://exemplo.com/audio.ogg"
}

Enviar vídeo

POST /instances/{id}/token/{token}/send-video

request

{
  "phone": "5511999999999",
  "video": "https://exemplo.com/video.mp4",
  "caption": "legenda"
}

Enviar documento

POST /instances/{id}/token/{token}/send-document/{extensão}

A extensão vai no caminho, por exemplo /send-document/pdf.

request

{
  "phone": "5511999999999",
  "document": "https://exemplo.com/arquivo.pdf",
  "fileName": "contrato.pdf"
}

Enviar localização

POST /instances/{id}/token/{token}/send-location

latitude e longitude são números, não strings.

request

{
  "phone": "5511999999999",
  "title": "Escritório",
  "address": "Av. Paulista, 1000",
  "latitude": -23.5615,
  "longitude": -46.656
}

Enviar contato

POST /instances/{id}/token/{token}/send-contact

request

{
  "phone": "5511999999999",
  "contactName": "João Silva",
  "contactPhone": "5511888888888",
  "contactBusinessDescription": "opcional"
}

Enviar link com preview

POST /instances/{id}/token/{token}/send-link

request

{
  "phone": "5511999999999",
  "message": "Confira:",
  "linkUrl": "https://zapbot.online",
  "title": "Zapbot",
  "linkDescription": "API de WhatsApp",
  "image": "https://exemplo.com/preview.png"
}

Enviar reação

POST /instances/{id}/token/{token}/send-reaction

O messageId é o mesmo devolvido no envio ou recebido no webhook.

request

{
  "phone": "5511999999999",
  "messageId": "3EB0C9A1F2D4",
  "reaction": "👍"
}

Webhook — mensagem recebida

O Zapbot faz POST na sua webhookUrl a cada mensagem recebida, com type: "ReceivedCallback".

texto

{
  "type": "ReceivedCallback",
  "instanceId": "b1a2c3d4-...",
  "messageId": "3EB0C9A1F2D4",
  "phone": "5511999999999",
  "connectedPhone": "5511777777777",
  "fromMe": false,
  "momment": 1720000000000,
  "senderName": "Maria",
  "isGroup": false,
  "text": { "message": "Oi!" }
}

imagem — mídia já re-hospedada

{
  "type": "ReceivedCallback",
  "phone": "5511999999999", /* ... */
  "image": {
    "imageUrl": "https://api.zapbot.online/media/uuid.jpg",
    "caption": "legenda",
    "mimeType": "image/jpeg"
  }
}

O campo que carrega o conteúdo muda conforme o tipo da mensagem:

Tipo	Campo no payload
Texto	`text.message`
Imagem	`image.imageUrl`, `image.caption`
Áudio	`audio.audioUrl`
Vídeo	`video.videoUrl`, `video.caption`
Documento	`document.documentUrl`, `document.fileName`
Figurinha	`sticker.stickerUrl`
Localização	`location.latitude`, `location.longitude`
Contato	`contact.displayName`, `contact.vCard`
Reação	`reaction.value`, `reaction.referencedMessage.messageId`
Enquete	`poll.question`, `poll.options[]`

Grupos, listas de transmissão, status e newsletters não geram webhook — apenas conversas 1:1.

Webhook — status de mensagem

Acompanha o ciclo de entrega das mensagens que você enviou.

MessageStatusCallback

{
  "type": "MessageStatusCallback",
  "status": "READ",   // SENT | RECEIVED | READ | PLAYED
  "phone": "5511999999999",
  "messageId": "3EB0C9A1F2D4"
}

Webhook — conexão

Disparado quando o número conclui o pareamento.

ConnectedCallback

{
  "type": "ConnectedCallback",
  "phone": "5511777777777",
  "connectedPhone": "5511777777777"
}