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 um QR code, ou com login_method=phone um código de 8 caracteres, para a URL do seu webhook. Mostre-o ao dono do celular, ele escaneia o QR code ou digita o código no WhatsApp e o número fica pronto para enviar mensagens. Com um QR code, você não precisa saber o número com antecedência: o WbizTool o lê do WhatsApp depois do escaneamento e o envia para o seu webhook.

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 ou o código chega depois, na URL do seu webhook.

1. Chame a API de conexão

   Envie o seu webhook_url, mais whatsapp_number com login_method=phone. Para reconectar um número que você adicionou antes, envie também o whatsapp_client_id dele. A resposta traz um whatsapp_client_id. Guarde-o.

2. Receba o QR code ou o código

   Com o padrão login_method=qr, seu webhook recebe status=qr_generated com a imagem do QR code em qr_image. 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.

   Com login_method=phone, seu webhook recebe status=pairing_code com um código de 8 caracteres em pairing_code, como K5EWPGY5. Ele é enviado uma única vez e é válido por cerca de três minutos.

   Mostre a imagem ou o código à pessoa dona do celular. Se não for usado a tempo, ou se o WhatsApp pedir para recarregar o código, você recebe not_connected; chame a API novamente para obter um novo.

3. Vincule o celular

   No celular, abra o WhatsApp → Dispositivos conectados (Linked devices) → Conectar dispositivo (Link a device). Escaneie o QR code, ou toque em Conectar com número de telefone (Link with phone number instead) e digite o código de 8 caracteres.

4. Receba o resultado

   Seu webhook recebe status=connected com o número vinculado em whatsapp_number 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",
    "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",
        "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",
    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',
    '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. Para receber um código no celular, adicione "login_method": "phone" e "whatsapp_number": "919876543210".

Parâmetros da requisição#

Usar os clientes oficiais#

O cliente Python chama /api/v1/whatsapp-client/create/ para você. Ele pede whatsapp_number; com um QR code, o valor é ignorado.

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,
  "login_method": "qr",
  "status": 1
}

"status": 1 significa que a solicitação foi criada, não que o número está conectado. Chamar a API novamente não acumula números:

• Com um QR code e sem whatsapp_client_id, você recebe o mesmo whatsapp_client_id de volta até que um dos QR codes dele seja escaneado.
• Com login_method=phone, um número que já foi adicionado antes, mas não está conectado, recebe de volta o whatsapp_client_id existente.
• Com whatsapp_client_id, esse número é reconectado.

Até o primeiro QR code ser escaneado, o número ainda não tem número de telefone: Listar números conectados e Status da conexão retornam um número vazio para ele.

Erros#

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

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=...

Código no celular pronto (com login_method=phone, enviado uma única vez):

status=pairing_code&whatsapp_client_id=678&pairing_code=K5EWPGY5

Número conectado, com o número que está logado, como o WhatsApp o informa:

status=connected&whatsapp_client_id=678&whatsapp_number=919876543210

Falha na conexão, por exemplo porque o QR code não foi escaneado ou o código não foi digitado 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 por até 10 segundos; se o seu servidor for lento ou não puder ser acessado, esse evento se perde, mas a tentativa de conexão continua. 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: faça com que seu handler possa ser executado mais de uma vez com segurança, caso um evento seja entregue duas vezes.
• 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.
• Confira o número depois de escanear o QR code: o whatsapp_number do evento connected é o número que foi realmente vinculado, que pode ser diferente do que você esperava.
• Digite o código em cerca de três minutos: cada tentativa gera um único código. Se ele expirar, você recebe not_connected; chame a API novamente.
• Nenhum QR code ou código 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á.