Passare dalla v1 alla v2

L'API v2 fa ciò che fa la v1, con chiavi più sicure, un unico stile di URL, veri codici di stato HTTP e webhook JSON firmati. Questa pagina mette in corrispondenza ogni endpoint e campo della v1 con il suo equivalente nella v2. Le novità della v2 sono descritte nella panoramica.

Cosa cambia ovunque#

• Chiavi: client_id + api_key della v1 diventano un unico header, Authorization: Bearer wbz_live_…. Crea una chiave v2 in Impostazioni → Chiavi API, nella scheda Chiavi API v2, solo con gli scope di cui l'app ha bisogno. Le chiavi v1 non funzionano sulla v2, e le chiavi v2 non funzionano sulla v1.
• Solo JSON: niente campi di un modulo. I file si caricano con POST /media (multipart) e si inviano tramite media_id.
• Metodi e URL: GET per leggere, POST per creare, PATCH per modificare, DELETE per annullare o eliminare, sotto https://wbiztool.com/api/v2.
• Codici di stato HTTP al posto di "status": 0 o 1 (vedi Risposte ed errori).
• Numeri di telefono in formato internazionale con +, senza country_code.
• Orari in ISO 8601 con un offset, invece di campi separati per data, ora e fuso orario.
• Webhook: sono endpoint che aggiungi una volta per lo spazio di lavoro, con eventi JSON firmati, invece di un URL webhook su ogni messaggio.

Endpoint per endpoint#

I percorsi v2 sono relativi a https://wbiztool.com/api/v2.

Invio, campo per campo#

Lo stesso invio nella v1 e nella v2:

# v1
curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Authorization: Bearer YOUR_V1_KEY" \
  -H "Content-Type: application/json" \
  -d '{"whatsapp_client": 101, "msg_type": 1, "country_code": "91", "phone": "9876543210",
       "img_url": "https://example.com/offers/diwali-sale.jpg", "msg": "Our Diwali sale starts today",
       "expire_after_seconds": 3600}'

# v2
curl -X POST https://wbiztool.com/api/v2/messages \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: diwali-9876543210" \
  -d '{"from": 101, "to": {"phone": "+919876543210"},
       "media": {"url": "https://example.com/offers/diwali-sale.jpg"}, "text": "Our Diwali sale starts today",
       "expires_at": "2026-10-20T11:30:00+05:30"}'

Alcuni comportamenti della v1 sono stati eliminati di proposito:

• Nessuna supposizione sui prefissi internazionali. La v1 anteponeva country_code al numero (con 91, sempre davanti a un numero di 10 cifre). La v2 prende il numero esattamente come è scritto, con +.
• Nessun download del file durante la chiamata. La v1 scaricava img_url e file_url durante la richiesta. La v2 controlla che il link sia pubblico e scarica il file quando il messaggio viene inviato; un link non valido si presenta come messaggio failed.
• Nessuna riga fallita in caso di rifiuto. Quando la v1 rifiuta un invio oltre il limite giornaliero di 1.000, salva comunque il messaggio come fallito. La v2 non salva nulla quando rifiuta un invio.
• I campi sconosciuti vengono rifiutati invece di essere ignorati.

Stati#

I numeri e le parole della v1 diventano un unico campo status:

Gli eventi webhook sono message.sent, message.failed, message.cancelled e message.expired, corrispondenti a SENT, FAILED, CANCELLED ed EXPIRED della v1.

Risposte ed errori#

La v1 risponde a molti errori con HTTP 200 o 400 e "status": 0, e al successo con "status": 1. La v2 usa il codice di stato HTTP:

• Il successo è 200, 201 (creato) o 202 (in coda), e il body è l'oggetto stesso, ad esempio il Messaggio. Non c'è nessun involucro status: 1.
• Gli errori sono 4xx o 5xx con un'unica struttura: {"error": {"code", "message", "field", "docs", "request_id"}}. Basa le condizioni su code, non sul message in inglese. Tutti i codici sono nella pagina degli errori.

# v1
result = response.json()
if result.get("status") == 1:
    msg_id = result["msg_id"]

# v2
if response.status_code == 202:
    message_id = response.json()["id"]
else:
    error = response.json()["error"]
    if error["code"] == "number_daily_cap_reached":
        ...  # try again tomorrow

Alcuni messaggi della v1 e i relativi codici v2:

Webhook#

Nella v1, ogni messaggio può avere un URL webhook che riceve un msg_id=…&status=SENT codificato come modulo. Nella v2:

1. Aggiungi un endpoint una sola volta con POST /webhooks e conserva il suo secret.
2. Riceve eventi JSON per tutti i messaggi dello spazio di lavoro, con l'intero Messaggio in data.message. Abbinali ai tuoi record tramite data.message.id.
3. Verifica la firma: lo stesso schema della v1 (WbizTool-Timestamp, WbizTool-Signature: v1=…), ma con il secret dell'endpoint invece di quello dello spazio di lavoro.
4. Scarta i duplicati con WbizTool-Event-Id. I nuovi tentativi continuano per circa 23 ore, non 4 tentativi in pochi minuti come nella v1, e anche le risposte 4xx vengono ritentate.

Gli eventi di collegamento della v1 (webhook_url su whatsapp/connect/) non hanno ancora un evento v2: interroga invece GET /numbers/{id}.

Una checklist#

1. Crea una chiave v2 per ogni app

   In Impostazioni → Chiavi API, solo con gli scope di cui ha bisogno. Provala prima con una chiave di test, che controlla tutto e non invia nulla.

2. Modifica le richieste

   Nuovi URL e metodi, body JSON, to / from / text / media, numeri di telefono con +, orari con offset. Aggiungi un Idempotency-Key a ogni invio.

3. Modifica la gestione degli errori

   Controlla lo stato HTTP, poi error.code. Gestisci il 429 aspettando Retry-After.

4. Sposta i webhook

   Aggiungi un endpoint, verifica le firme con il suo secret e scarta i duplicati tramite l'id dell'evento.

5. Passa alla v2 e revoca

   Quando l'app funziona sulla v2, elimina la sua chiave v1 in Impostazioni → Chiavi API.

Pagine correlate#

• Panoramica dell'API v2
• Messaggi
• Webhook
• Errori
• Chiavi API e Client ID (v1)