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 il codice QR al tuo URL webhook. Mostralo al proprietario del telefono, che lo scansiona da WhatsApp, e il numero è pronto per inviare messaggi.

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 arriva in un secondo momento, al tuo URL webhook.

1. Chiama l'API di collegamento

   Invia il numero di telefono e il tuo webhook_url. La risposta ti restituisce un whatsapp_client_id. Salvalo.

2. Ricevi il codice QR

   Il tuo webhook riceve status=qr_generated con l'immagine QR in qr_image. Mostra quell'immagine alla persona proprietaria del telefono. 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. Dopo questo tempo, o se WhatsApp chiede di ricaricare il codice, ricevi not_connected; chiama di nuovo l'API per ottenere un nuovo codice.

3. Scansionalo da WhatsApp

   Sul telefono, apri WhatsApp → Dispositivi collegati → Collega un dispositivo e scansiona il codice.

4. Ottieni il risultato

   Il tuo webhook riceve status=connected 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",
    "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');
}

Sostituisci 12345 e YOUR_API_KEY con i tuoi valori. Consulta Autenticazione per sapere dove trovarli.

Parametri della richiesta#

Usare i client ufficiali#

Il client Python chiama /api/v1/whatsapp-client/create/ per te.

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

"status": 1 significa che la richiesta è stata creata, non che il numero sia collegato. Se chiami di nuovo l'API per un numero aggiunto in precedenza ma non collegato, ricevi lo stesso whatsapp_client_id e parte un nuovo tentativo di collegamento.

Errori#

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

Se lo stesso proprietario dell'account ha già aggiunto questo numero in un altro spazio di lavoro, la richiesta può non riuscire con HTTP 500. Collega il numero dalle Impostazioni WhatsApp nello spazio di lavoro che preferisci, oppure contatta l'assistenza.

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 lo stesso URL):

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

Numero collegato (può essere inviato più di una volta per lo stesso collegamento):

status=connected&whatsapp_client_id=678

Collegamento non riuscito, ad esempio perché il codice QR non è stato scansionato 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 senza timeout. Se il tuo server non è raggiungibile, il tentativo di collegamento può interrompersi prima che il numero venga salvato come collegato. È 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: connected può arrivare due volte. Fai in modo che il tuo handler possa essere eseguito più volte senza problemi.
• 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.
• Nessun codice QR 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.