Collegare un numero WhatsApp (API)

Avvia il collegamento di un numero WhatsApp al tuo spazio di lavoro dalla tua app. WbizTool apre una nuova sessione WhatsApp e invia al tuo URL webhook un codice QR oppure, con login_method=phone, un codice di 8 caratteri. Mostralo al proprietario del telefono, che scansiona il codice QR o digita il codice in WhatsApp, e il numero è pronto per inviare messaggi. Con un codice QR non devi conoscere il numero in anticipo: WbizTool lo legge da WhatsApp dopo la scansione e lo invia al tuo webhook.

Colleghi il tuo numero a mano? Segui Collega il tuo numero WhatsApp.

POST /api/v1/whatsapp-client/create/ è un alias identico: esegue lo stesso codice e restituisce le stesse risposte. Entrambi i percorsi continuano a funzionare.

Come funziona il collegamento#

La chiamata API avvia soltanto il collegamento. Il codice QR o il codice telefonico arriva in un secondo momento, al tuo URL webhook.

1. Chiama l'API di collegamento

   Invia il tuo webhook_url, più whatsapp_number con login_method=phone. Per ricollegare un numero aggiunto in precedenza, invia anche il suo whatsapp_client_id. La risposta ti restituisce un whatsapp_client_id. Salvalo.

2. Ricevi il codice QR o il codice telefonico

   Con il valore predefinito login_method=qr, il tuo webhook riceve status=qr_generated con l'immagine QR in qr_image. Il codice QR viene inviato di nuovo ogni pochi secondi mentre WbizTool attende la scansione, quindi mostra sempre il più recente. La persona ha circa due minuti per scansionarlo.

   Con login_method=phone, il tuo webhook riceve status=pairing_code con un codice di 8 caratteri in pairing_code, ad esempio K5EWPGY5. Viene inviato una sola volta ed è valido per circa tre minuti.

   Mostra l'immagine o il codice alla persona proprietaria del telefono. Se non viene usato in tempo, o se WhatsApp chiede di ricaricare il codice, ricevi not_connected; chiama di nuovo l'API per ottenerne uno nuovo.

3. Collega il telefono

   Sul telefono, apri WhatsApp → Dispositivi collegati → Collega un dispositivo. Scansiona il codice QR, oppure tocca Collega con il numero di telefono e digita il codice di 8 caratteri.

4. Ottieni il risultato

   Il tuo webhook riceve status=connected con il numero collegato in whatsapp_number quando il numero è collegato, oppure status=not_connected se il codice non è stato scansionato in tempo o il collegamento non è riuscito. L'evento connected può arrivare qualche secondo prima che Stato della connessione restituisca Connected. Rispondi prima al webhook, poi interroga Stato della connessione ogni pochi secondi per un minuto al massimo. Non controllarlo una sola volta dall'interno del gestore del webhook.

Esempio rapido#

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');
}

Sostituisci 12345 e YOUR_API_KEY con i tuoi valori. Consulta Autenticazione per sapere dove trovarli. Per ottenere invece un codice telefonico, aggiungi "login_method": "phone" e "whatsapp_number": "919876543210".

Parametri della richiesta#

Usare i client ufficiali#

Il client Python chiama /api/v1/whatsapp-client/create/ per te. Richiede whatsapp_number; con un codice QR il valore viene ignorato.

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)

Il client Python solleva requests.exceptions.HTTPError quando l'API restituisce HTTP 400 o 403, quindi racchiudi la chiamata in un try/except.

Risposta#

Quando la richiesta di collegamento viene creata, l'API restituisce HTTP 200:

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

"status": 1 significa che la richiesta è stata creata, non che il numero sia collegato. Chiamare di nuovo l'API non accumula numeri:

• Con un codice QR e senza whatsapp_client_id, ricevi lo stesso whatsapp_client_id finché uno dei suoi codici QR non viene scansionato.
• Con login_method=phone, un numero aggiunto in precedenza ma non collegato riceve il suo whatsapp_client_id esistente.
• Con whatsapp_client_id, quel numero viene ricollegato.

Finché il suo primo codice QR non viene scansionato, il numero non ha ancora un numero di telefono: Elencare i numeri collegati e Stato della connessione restituiscono un numero vuoto per esso.

Errori#

Una richiesta che non è una POST restituisce un oggetto vuoto {} con HTTP 200.

Eventi webhook#

WbizTool invia una POST al tuo webhook_url a ogni passaggio. Il corpo è codificato come modulo (application/x-www-form-urlencoded), non JSON.

Codice QR pronto (inviato di nuovo ogni pochi secondi durante l'attesa della scansione, spesso con la stessa immagine):

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

Codice telefonico pronto (con login_method=phone, inviato una sola volta):

status=pairing_code&whatsapp_client_id=678&pairing_code=K5EWPGY5

Numero collegato, con il numero collegato, come lo indica WhatsApp:

status=connected&whatsapp_client_id=678&whatsapp_number=919876543210

Collegamento non riuscito, ad esempio perché il codice QR non è stato scansionato o il codice telefonico non è stato inserito in tempo:

status=not_connected&whatsapp_client_id=678

Il tuo URL deve essere raggiungibile pubblicamente e dovrebbe rispondere entro pochi secondi. WbizTool attende la tua risposta per un massimo di 10 secondi; se il tuo server è lento o non è raggiungibile, quell'evento va perso ma il tentativo di collegamento prosegue. È accettato qualsiasi codice di stato HTTP. Le consegne non riuscite non vengono ritentate e non viene inviato nulla se in seguito il numero si scollega. Per seguire un numero dopo il collegamento, interroga periodicamente Stato della connessione.

Polling al posto dei webhook#

Se il tuo server non può ricevere webhook, il webhook ti serve comunque per ottenere il codice QR, ma non devi dipendere da esso per il risultato. Dopo la scansione del codice QR, chiama Stato della connessione con il whatsapp_client_id ogni pochi secondi finché non restituisce Connected. Elenca account mostra la stessa informazione per tutti i tuoi numeri.

Suggerimenti#

• Gestisci gli eventi duplicati: fai in modo che il tuo handler possa essere eseguito più volte senza problemi, nel caso in cui un evento venga consegnato due volte.
• Mostra il codice QR più recente: sostituisci l'immagine ogni volta che arriva un nuovo evento qr_generated, aggiungendo una query per evitare la cache a un URL https. I codici precedenti smettono di funzionare.
• Scansiona entro circa due minuti: dopo questo tempo ricevi not_connected. Chiama di nuovo l'API per un nuovo codice.
• Controlla il numero dopo la scansione di un codice QR: il whatsapp_number dell'evento connected è il numero realmente collegato, che può essere diverso da quello che ti aspettavi.
• Inserisci il codice telefonico entro circa tre minuti: ogni tentativo fornisce un solo codice. Se scade ricevi not_connected; chiama di nuovo l'API.
• Nessun codice QR o codice telefonico dopo 10 minuti? La richiesta è scaduta. Chiama di nuovo l'API.
• Collegare dalla dashboard è più semplice quando colleghi il tuo numero. Usa le Impostazioni WhatsApp e scansiona lì il codice.