Conectar um número de WhatsApp (API)

Inicie a conexão de um número de WhatsApp ao seu espaço de trabalho a partir do seu próprio app. O Wbiztool abre uma nova sessão do WhatsApp e envia o QR code para a URL do seu webhook. Mostre-o ao dono do celular, ele o escaneia pelo WhatsApp e o número fica pronto para enviar mensagens.

Vai conectar o seu próprio número manualmente? Siga Conecte seu número de WhatsApp.

POST /api/v1/whatsapp-client/create/ é um alias idêntico: executa o mesmo código e retorna as mesmas respostas. Os dois caminhos continuam funcionando.

Como a conexão funciona#

A chamada à API apenas inicia a conexão. O QR code chega depois, na URL do seu webhook.

1. Chame a API de conexão

   Envie o número de telefone e o seu webhook_url. A resposta traz um whatsapp_client_id. Guarde-o.

2. Receba o QR code

   Seu webhook recebe status=qr_generated com a imagem do QR code em qr_image. Mostre essa imagem à pessoa dona do celular. O QR code é enviado novamente a cada poucos segundos enquanto o Wbiztool aguarda o escaneamento, então sempre mostre o mais recente. A pessoa tem cerca de dois minutos para escanear. Depois disso, ou se o WhatsApp pedir para recarregar o código, você recebe not_connected; chame a API novamente para obter um novo código.

3. Escaneie pelo WhatsApp

   No celular, abra o WhatsApp → Dispositivos conectados (Linked devices) → Conectar dispositivo (Link a device) e escaneie o código.

4. Receba o resultado

   Seu webhook recebe status=connected quando o número é conectado, ou status=not_connected se o código não foi escaneado a tempo ou a conexão falhou. O evento connected pode chegar alguns segundos antes de Status da conexão retornar Connected. Responda primeiro ao webhook e depois consulte Status da conexão a cada poucos segundos por até um minuto. Não faça uma única verificação de dentro do handler do seu webhook.

Exemplo rápido#

curl -X POST https://wbiztool.com/api/v1/whatsapp/connect/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_number": "919876543210",
    "webhook_url": "https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET"
  }'

import requests

response = requests.post(
    "https://wbiztool.com/api/v1/whatsapp/connect/",
    json={
        "client_id": 12345,
        "api_key": "YOUR_API_KEY",
        "whatsapp_number": "919876543210",
        "webhook_url": "https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET",
    },
    timeout=30,
)
result = response.json()  # read the body even when the HTTP code is 400 or 403

if result.get("status") == 1:
    print("Waiting for QR code, whatsapp_client_id", result["whatsapp_client_id"])
else:
    print("Failed:", result.get("message"))

// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v1/whatsapp/connect/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    client_id: 12345,
    api_key: "YOUR_API_KEY",
    whatsapp_number: "919876543210",
    webhook_url: "https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET",
  }),
});
const result = await response.json(); // read the body even when the HTTP code is 400 or 403

if (result.status === 1) {
  console.log("Waiting for QR code, whatsapp_client_id", result.whatsapp_client_id);
} else {
  console.error("Failed:", result.message);
}

<?php
$payload = [
    'client_id'       => 12345,
    'api_key'         => 'YOUR_API_KEY',
    'whatsapp_number' => '919876543210',
    'webhook_url'     => 'https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET',
];

$ch = curl_init('https://wbiztool.com/api/v1/whatsapp/connect/');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if (($result['status'] ?? 0) === 1) {
    echo 'Waiting for QR code, whatsapp_client_id ' . $result['whatsapp_client_id'];
} else {
    echo 'Failed: ' . ($result['message'] ?? 'no response');
}

Substitua 12345 e YOUR_API_KEY pelos seus próprios valores. Veja em Autenticação onde encontrá-los.

Parâmetros da requisição#

Usar os clientes oficiais#

O cliente Python chama /api/v1/whatsapp-client/create/ para você.

from wbiztool_client import WbizToolClient

client = WbizToolClient(api_key="YOUR_API_KEY", client_id=12345)

result = client.create_whatsapp_client(
    whatsapp_number="919876543210",
    webhook_url="https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET",
)
print(result)

O cliente Python lança requests.exceptions.HTTPError quando a API retorna HTTP 400 ou 403, então coloque a chamada dentro de um try/except.

Resposta#

Quando a solicitação de conexão é criada, a API retorna HTTP 200:

{
  "message": "Whatsapp Client Created",
  "whatsapp_client_id": 678,
  "status": 1
}

"status": 1 significa que a solicitação foi criada, não que o número está conectado. Se você chamar a API novamente para um número que já foi adicionado antes, mas não está conectado, recebe o mesmo whatsapp_client_id de volta e uma nova tentativa de conexão é iniciada.

Erros#

Uma requisição que não seja POST retorna um objeto vazio {} com HTTP 200.

Se o mesmo proprietário da conta já tiver adicionado este número em outro espaço de trabalho, a requisição pode falhar com HTTP 500. Conecte o número pelas configurações do WhatsApp no espaço de trabalho desejado, ou fale com o suporte.

Eventos de webhook#

O Wbiztool envia um POST para o seu webhook_url a cada etapa. O corpo é codificado como formulário (application/x-www-form-urlencoded), não como JSON.

QR code pronto (enviado novamente a cada poucos segundos enquanto aguarda o escaneamento, muitas vezes com a mesma URL):

status=qr_generated&whatsapp_client_id=678&qr_image=...

Número conectado (pode ser enviado mais de uma vez para a mesma conexão):

status=connected&whatsapp_client_id=678

Falha na conexão, por exemplo porque o QR code não foi escaneado a tempo:

status=not_connected&whatsapp_client_id=678

Sua URL precisa ser acessível publicamente e deve responder em poucos segundos. O Wbiztool aguarda sua resposta sem tempo limite. Se o seu servidor não puder ser acessado, a tentativa de conexão pode parar antes de o número ser salvo como conectado. Qualquer código de status HTTP é aceito. Entregas que falham não são repetidas, e nada é enviado se o número se desconectar depois. Para acompanhar um número depois de conectado, consulte periodicamente Status da conexão.

Polling em vez de webhooks#

Se o seu servidor não consegue receber webhooks, você ainda precisa do webhook para obter o QR code, mas não precisa depender dele para saber o resultado. Depois que o QR code for escaneado, chame Status da conexão com o whatsapp_client_id a cada poucos segundos até que ele retorne Connected. Listar contas mostra a mesma informação para todos os seus números.

Dicas#

• Trate eventos duplicados: connected pode chegar duas vezes. Faça com que seu handler possa ser executado mais de uma vez com segurança.
• Mostre o QR code mais recente: substitua a imagem sempre que chegar um novo evento qr_generated, adicionando uma query para evitar cache a uma URL https. Os códigos antigos param de funcionar.
• Escaneie em cerca de dois minutos: depois disso, você recebe not_connected. Chame a API novamente para obter um novo código.
• Nenhum QR code depois de 10 minutos? A solicitação expirou. Chame a API novamente.
• Conectar pelo painel é mais simples quando você está conectando seu próprio número. Use as configurações do WhatsApp e escaneie o código lá.