← zapbot

Documentação da API

O Zapbot expõe uma API HTTP compatível com a Z-API: mesmos caminhos, mesmo formato de credenciais e mesmo formato de webhook. Se você já integra com a Z-API, basta trocar a URL base.

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 presentes na URL. Um cabeçalho opcional Client-Token adiciona segurança em nível de conta.

Autenticação

Camada	Onde	Descrição
`instanceId` + `token`	Caminho da URL	Identificam e autorizam a instância.
`Client-Token`	Header HTTP	Opcional. Se definido na instância, é obrigatório em toda requisição.
`Authorization: Bearer`	Header HTTP	Apenas nos endpoints administrativos (`/admin/*`).

URL base

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

Migrando da Z-API? Troque api.z-api.io por api.zapbot.online. Corpo, headers e respostas permanecem idênticos.

Criar instância

POST /admin/instances

Requer Authorization: Bearer <ADMIN_TOKEN>.

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

// 201 Created
{
  "id": "b1a2...",
  "token": "f9e8...",
  "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 telefone conectado.

Deletar instância

DELETE /admin/instances/{id}

Desconecta o número e remove a instância.

Status da conexão

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

// 200 OK
{
  "connected": true,
  "session": true,
  "smartphoneConnected": true
}

QR Code

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

Inicia o pareamento (se necessário) e retorna o QR Code como imagem PNG em base64. Escaneie no WhatsApp > Aparelhos conectados.

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

Também disponível: GET /qr-code (retorna o conteúdo bruto do QR em value) e GET /restart (reconecta).

Desconectar

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

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

{ "phone": "5511999999999", "message": "Olá!" }

// 200 OK — resposta padrão de todos os send-*
{ "zaapId": "...", "messageId": "3EB0...", "id": "3EB0..." }

Enviar imagem

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

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

image aceita URL http(s) ou data URI base64 (data:image/png;base64,...).

Enviar áudio

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

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

Enviar vídeo

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

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

Enviar documento

POST /instances/{id}/token/{token}/send-document/{extension}

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

A extensão vai no caminho, ex.: /send-document/pdf.

Enviar localização

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

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

Enviar contato

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

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

Enviar link (com preview)

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

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

Enviar reação

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

{ "phone": "5511999999999",
  "messageId": "3EB0...", "reaction": "👍" }

Webhook — Mensagem recebida

O Zapbot faz POST no seu webhookUrl com o corpo abaixo (type: "ReceivedCallback"). O formato é idêntico ao da Z-API.

// texto
{
  "type": "ReceivedCallback",
  "instanceId": "b1a2...",
  "messageId": "3EB0...",
  "phone": "5511999999999",
  "connectedPhone": "5511777777777",
  "fromMe": false,
  "momment": 1720000000000,
  "senderName": "Maria",
  "isGroup": false,
  "text": { "message": "Oi!" }
}

// imagem — mídia re-hospedada e servida por URL pronta
{
  "type": "ReceivedCallback", "phone": "5511999999999", /* ... */
  "image": { "imageUrl": "https://api.zapbot.online/media/uuid.jpg",
             "caption": "legenda", "mimeType": "image/jpeg" }
}

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`
Sticker	`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 são ignorados — apenas conversas 1:1 geram webhook, seguindo o mesmo comportamento esperado pelo gateway.

Webhook — Status de mensagem

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

Webhook — Conexão

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