Connect para WhatsApp

Endpoints para autenticar aplicações, consultar instâncias, iniciar conexão por QR Code e enviar mensagens pelo WhatsApp. Mensagens recebidas são encaminhadas ao webhook do cliente; a Connect API mantém apenas contadores e metadados mínimos.

Começando

Use sua credencial para gerar um Bearer Token e envie esse token nas rotas protegidas.

Gerenciar credenciais

Base URL

https://localhost/api/v1

POST /auth/token

curl -X POST https://localhost/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "bbx_1234567890",
    "client_secret": "sk_live_1234567890"
  }'

{
  "access_token": "eyJ0eXAi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Headers das rotas protegidas

Authorization
Bearer SEU_ACCESS_TOKEN

Content-Type
application/json

Accept
application/json

Endpoints

Rotas públicas para integrar sua aplicação com uma instância de WhatsApp.

Método	Endpoint	Descrição
POST	`/auth/token`	Gera token de acesso a partir de Client ID e Client Secret.
GET	`/webhook`	Consulta a URL configurada para eventos recebidos.
POST	`/webhook`	Configura a URL que receberá eventos `message.received`.
GET	`/whatsapp/{instance_id}/status`	Consulta o estado atual da instância.
GET	`/whatsapp/{instance_id}/qr-code`	Retorna o QR Code atual em base64 quando a instância está aguardando leitura.
POST	`/whatsapp/{instance_id}/start`	Solicita a inicialização da sessão no bridge WhatsApp.
POST	`/whatsapp/{instance_id}/send-text`	Envia uma mensagem de texto.
POST	`/whatsapp/{instance_id}/send-image`	Envia uma imagem por URL pública, com legenda opcional.
POST	`/whatsapp/{instance_id}/send`	Endpoint compatível para texto, imagem ou ambos.

POST Configurar webhook

Defina a URL do seu sistema que receberá as mensagens recebidas pela instância.

curl -X POST https://localhost/api/v1/webhook \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://api.seusistema.com/webhooks/script"
  }'

{
  "success": true,
  "message": "Webhook atualizado com sucesso.",
  "data": {
    "webhook_url": "https://api.seusistema.com/webhooks/script",
    "event": "message.received"
  }
}

Evento enviado ao cliente

Quando uma mensagem chega no WhatsApp, a Connect envia este payload para o webhook configurado.

{
  "event": "message.received",
  "instance_id": "tenant_1_abcd123",
  "message_id": "3A8F...",
  "from": "5511999999999@s.whatsapp.net",
  "sender_name": "Cliente",
  "type": "link",
  "message": {
    "text": "https://www.mercadolivre.com.br/",
    "url": "https://www.mercadolivre.com.br/"
  },
  "timestamp": "2026-06-12T10:30:00-03:00"
}

O campo type pode ser text, link, document, image, audio, video, contact, location, sticker, button ou option.

GET Consultar status

Use para saber se a instância está conectada antes de enviar mensagens.

curl -X GET https://localhost/api/v1/whatsapp/tenant_1_abcd123/status \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

{
  "success": true,
  "data": {
    "instance_id": "tenant_1_abcd123",
    "name": "Suporte",
    "status": "CONNECTED",
    "connected": true,
    "updated_at": "2026-06-12 10:30:00"
  }
}

GET Obter QR Code

Quando o status for WAITING_QR, leia o valor de qr_code em uma tag de imagem.

curl -X GET https://localhost/api/v1/whatsapp/tenant_1_abcd123/qr-code \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

{
  "success": true,
  "data": {
    "instance_id": "tenant_1_abcd123",
    "status": "WAITING_QR",
    "qr_code": "data:image/png;base64,iVBORw0KGgo...",
    "expires_in": 45
  }
}

POST Iniciar instância

Dispara o processo de conexão. Depois consulte o QR Code até conectar.

curl -X POST https://localhost/api/v1/whatsapp/tenant_1_abcd123/start \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

{
  "success": true,
  "message": "Inicializacao solicitada com sucesso.",
  "data": {
    "instance_id": "tenant_1_abcd123",
    "status": "STARTING",
    "bridge": {
      "message": "Comando de inicializacao enviado para a instancia tenant_1_abcd123."
    },
    "updated_at": "2026-06-12 10:30:00"
  }
}

POST Enviar texto

Compatível com message ou text no corpo JSON.

Campo	Tipo	Obrigatório	Descrição
`phone`	string	Sim	Número com DDI e DDD. Exemplo: `5511999999999`.
`message`	string	Sim	Texto que será enviado ao contato.

curl -X POST https://localhost/api/v1/whatsapp/tenant_1_abcd123/send-text \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "message": "Olá! Seu pedido foi aprovado."
  }'

POST Enviar imagem

Use uma URL pública de imagem. A legenda pode ir em caption, message ou text.

curl -X POST https://localhost/api/v1/whatsapp/tenant_1_abcd123/send-image \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "image": "https://cdn.seusite.com/comprovante.png",
    "caption": "Segue o comprovante."
  }'

{
  "success": true,
  "message": "Mensagem enviada com sucesso.",
  "data": {
    "instance_id": "tenant_1_abcd123",
    "phone": "5511999999999",
    "status": "sent"
  }
}

Erros

Erros seguem o mesmo envelope para facilitar tratamento no cliente.

Status	Quando ocorre
`401`	Token ausente, inválido ou expirado.
`404`	Instância não encontrada para o tenant autenticado.
`409`	Instância existe, mas ainda não está conectada.
`422`	Campos obrigatórios ausentes ou inválidos.
`502`	Falha ao se comunicar com o bridge WhatsApp.

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "O campo phone e obrigatorio.",
    "details": {
      "phone": ["Informe o numero com DDI e DDD. Exemplo: 5511999999999."]
    }
  }
}