Skip to main content

​
O fluxo principal (visão geral)

  1. Criar instância → a resposta já traz o QR (connection.base64).
  2. Escanear o QR no WhatsApp do celular até o status ficar ACTIVE (ou ouvir webhooks instance.* / atualizar com GET .../qr).
  3. Enviar mensagem com POST /v1/whatsapp/messages usando o instanceId ativo.
Os passos abaixo repetem isso com exemplos de request/response.

​
Pré-requisitos

  • API Key com escopos: whatsapp:instances:create, whatsapp:instances:list, whatsapp:send (e opcionalmente whatsapp:read, whatsapp:instances:disconnect).
  • Envie a API Key em toda requisição:
    • Header: Authorization: Bearer sk_live_xxxxx
    • ou Header: x-api-key: sk_live_xxxxx

​
1. Criar instância

Crie uma instância WhatsApp no workspace. A resposta traz a instância e o QR code para pareamento (quando o status for PENDING). Request 
POST /v1/whatsapp/instances
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Minha Instância"
}
Response (200) 
{
  "success": true,
  "data": {
    "instance": {
      "id": "cmmc8wjkt000dqf01d2nlb0gv",
      "name": "Minha Instância",
      "status": "PENDING",
      "phoneNumber": null,
      "createdAt": "2026-03-04T16:22:50.909Z"
    },
    "connection": {
      "pairingCode": null,
      "code": "2@KbXFfHsvo+byvkP6k4VoBIE5gZFwYHT9y6dNt/c6Sfg6M+...",
      "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAVwAAAFcCAYAAACEFgYs...",
      "count": 1
    }
  }
}
  • instance: dados da instância criada (id, name, status PENDING até conectar, phoneNumber preenchido após pareamento).
  • connection: dados para exibir o QR e parear:
    • base64: imagem do QR em Data URL; use para exibir (ex.: <img src="connection.base64" />).
    • code: código interno de conexão.
    • pairingCode: código de pareamento quando disponível (pode ser null).
    • count: contador da geração do QR.
O QR code vem em connection.base64.

​
2. Obter / atualizar QR code

O QR expira após alguns segundos. Para obter o QR mais atual sem depender só do webhook: Request 
GET /v1/whatsapp/instances/:instanceId/qr
Authorization: Bearer sk_live_xxxxx
Response (200) — instância aguardando QR 
{
  "success": true,
  "data": {
    "status": "PENDING",
    "base64": "data:image/png;base64,iVBORw0KGgo..."
  }
}
Response (200) — instância já conectada 
{
  "success": true,
  "data": {
    "status": "ACTIVE",
    "base64": null
  }
}
Você pode fazer polling nesse endpoint ou usar o webhook instance.qrcode (o payload traz data.base64 completo).

​
3. Receber eventos (webhook)

Configure um webhook (API de Webhooks) com eventos:
  • instance.qrcode — novo QR gerado (payload inclui data.base64 completo).
  • instance.connected — WhatsApp conectado (data.phone_number).
  • instance.disconnected — instância desconectada.
Valide a assinatura com o secret do webhook:
  • Conteúdo: timestamp + "." + body (body bruto UTF-8).
  • Algoritmo: HMAC-SHA256(secret, conteúdo).
  • Header: X-Notifique-Signature: t=<timestamp>,v1=<hex>; X-Notifique-Timestamp = mesmo timestamp. Rejeite requisições com timestamp fora de uma janela (ex.: 5 minutos).

​
4. Enviar mensagem

Com a instância ACTIVE, envie uma mensagem de texto: Request 
POST /v1/whatsapp/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "instanceId": "clxx...",
  "to": ["5511999999999"],
  "type": "text",
  "payload": {
    "message": "Olá! Mensagem de teste."
  }
}
Response (202) 
{
  "messageIds": ["clxxmsg..."],
  "status": "QUEUED",
  "scheduledAt": null
}

​
Referências

  • GET da instância não retorna QR; use GET /v1/whatsapp/instances/:id/qr quando status for PENDING ou DISCONNECTED.