Vai al contenuto
WbizTool

API di messaggistica

API Invia messaggio

Invia un testo, un'immagine o un documento WhatsApp a un numero di telefono dal tuo numero WhatsApp collegato. Usala per conferme d'ordine, promemoria di pagamento, avvisi e risposte dell'assistenza.

POSThttps://wbiztool.com/api/v1/send_msg/

Corpo: JSON, campi di un modulo o multipart/form-data quando carichi un file

Il messaggio viene messo in coda e inviato dal tuo numero WhatsApp in pochi istanti. La risposta ti restituisce un msg_id che puoi usare per verificarne lo stato.

Esempio rapido#

curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsapp_client": 678,
    "msg_type": 0,
    "country_code": "91",
    "phone": "9876543210",
    "msg": "Hi Aman, your order #4821 has shipped and will arrive on Thursday."
  }'

Sostituisci YOUR_API_KEY e 678 con la tua chiave e l'ID del tuo numero. Consulta Autenticazione per sapere dove trovarli. La chiave va nell'header Authorization: Bearer (consigliato); funzionano anche client_id e api_key nel corpo, come JSON o campi di un modulo: gli esempi più avanti usano questi.

Parametri della richiesta#

Autenticazione

AuthorizationheaderConsigliato

Bearer YOUR_API_KEY: la tua chiave API da Impostazioni → Chiavi API. Con l'header, client_id e api_key si possono omettere dal corpo; se invii la chiave in entrambi i punti, viene usata una chiave valida nell'header. Vedi Inviare la chiave in un header.

client_idintegerSenza l'header Authorization

Il tuo ID Client API, da Impostazioni → Chiavi API. Facoltativo con l'header; se lo invii, deve essere quello dello spazio di lavoro della chiave.

api_keystringSenza l'header Authorization

La tua chiave API, dalla stessa pagina, quando non la invii nell'header.

whatsapp_clientintegerObbligatorio se hai più di un numero

ID del numero WhatsApp o dell'account Telegram da cui inviare, dalle Impostazioni WhatsApp. Se lo ometti, viene usato l'unico numero collegato, prima WhatsApp: un solo numero WhatsApp collegato viene usato anche se è collegato anche un account Telegram, e un account Telegram solo quando nessun numero WhatsApp è collegato. Un @username usa l'unico account Telegram collegato.

Destinatario e messaggio

phonestringobbligatorio

Il numero WhatsApp del destinatario. Spazi, +, -, ., parentesi e un 00 iniziale vengono rimossi automaticamente, quindi +91 98765-43210 funziona. I valori da foglio di calcolo come 919876543210.0 e 9.19876543210E+11 vengono letti come le loro cifre, ma uno arrotondato come 9.19877E+11 viene rifiutato, perché mancano delle cifre. Invia il numero con il prefisso internazionale (919876543210) oppure senza (9876543210) insieme a country_code. Funziona anche un numero locale scritto con il suo 0 iniziale: 09876543210 con country_code 91 va a 919876543210, e 0612345678 con 39 (Italia, dove lo 0 fa parte del numero) va a 390612345678. Un numero scritto con + o 00 porta con sé il proprio prefisso internazionale: country_code non gli viene aggiunto, e uno (0) tra parentesi dopo il prefisso viene eliminato, quindi +44 (0)20 7946 0018 va a 442079460018. Da un account Telegram, phone può essere anche un @username, un link t.me/username o tg:<id>.

country_codestringfacoltativo

Prefisso internazionale senza +, ad esempio 91 per l'India o 1 per gli USA. Viene aggiunto davanti a phone, a meno che il numero non inizi già con esso o non sia scritto con + o 00. Eccezione: con 91, a un numero di 10 cifre il prefisso viene sempre aggiunto. Con gli altri prefissi, a un numero locale che inizia con le stesse cifre il prefisso non viene aggiunto, quindi invialo con il prefisso internazionale già incluso.

msg_typeintegerfacoltativo

0 testo (predefinito), 1 immagine, 2 file o documento.

msgstringObbligatorio quando msg_type è 0

Testo del messaggio, fino a 3.000 caratteri. Per immagini e file è la didascalia e può essere vuoto. La formattazione di WhatsApp funziona: *bold*, _italic_, ~strikethrough~. message è accettato come alias.

Immagini e file

img_urlstringObbligatorio quando msg_type è 1 e non viene caricato alcun file

URL pubblico http o https dell'immagine.

file_urlstringObbligatorio quando msg_type è 2 e non viene caricato alcun file

URL pubblico http o https da cui il file può essere scaricato direttamente.

filefilefacoltativo

Carica l'immagine o il file invece di fornire un URL. Invia la richiesta come multipart/form-data con il campo chiamato file.

file_namestringfacoltativo

Nome del file che vede il destinatario, ad esempio invoice-4821.pdf. La sua estensione determina come viene inviato il file, quindi includila. Viene inviato in minuscolo, caratteri come & : ? * $ ; vengono sostituiti con _ e viene troncato a 150 caratteri. Se lo ometti, il nome viene preso dall'URL o dal file caricato.

Opzioni di consegna

expire_after_secondsintegerfacoltativo

Segna il messaggio come scaduto (stato 4) se non è stato inviato entro questo numero di secondi, ad esempio 3600 per un'ora. Utile per messaggi urgenti come orari di consegna previsti. Lo fa un processo in background almeno 30 secondi dopo la scadenza, quindi non farci affidamento per scadenze inferiori a un minuto.

webhookstringfacoltativo

URL che riceve una POST quando il messaggio viene inviato, non riesce, viene annullato o scade. Vedi Webhook.

Invio di immagini e file#

Limiti di download per img_url e file_url:

  • L'URL deve essere pubblico: http o https, raggiungibile da internet. Vengono seguiti fino a 5 reindirizzamenti, e ognuno deve portare anch'esso a un indirizzo pubblico.
  • I file collegati possono arrivare a 100 MB. Il server deve iniziare a rispondere entro 45 secondi e non bloccarsi per più di questo tempo.
  • Il file viene scaricato quando chiami l'API, quindi un link non funzionante fallisce subito con Invalid file url.

I file inviati con msg_type 2 mantengono queste estensioni:

CategoriaEstensioni
Immagini.jpg, .jpeg, .jpe, .png, .gif, .webp, .bmp
Documenti.pdf, .doc, .docx, .docm, .xls, .xlsx, .xlsm, .xlsb, .ppt, .pptx, .pptm, .txt, .csv
Audio.mp3, .mpga, .m4a, .aac, .wav, .ogg, .oga
Video.mp4, .mov, .avi, .webm
Archivi.zip, .rar

Questi controlli vengono eseguiti quando il messaggio viene inviato, non quando chiami l'API, quindi gli errori compaiono solo in Stato del messaggio e nel webhook:

Problemaerror in Stato del messaggio
Un'immagine (msg_type 1) oltre 16 MBFile exceeds WhatsApp size limit (16MB max)
Un video (.mp4, .webm) oltre 64 MB, anche se inviato come immagine (msg_type 1)File exceeds WhatsApp size limit (64MB max)
Qualsiasi altro file (msg_type 2) oltre 100 MBFile exceeds WhatsApp size limit (100MB max)
Un file vuoto (0 byte)The file is empty
Un file .wav o .ogg inviato come immagine (msg_type 1)File type not supported

L'audio WAV e OGG non si può inviare come immagine (msg_type 1). Inviati come file (msg_type 2), arrivano come documento con il loro nome, ad esempio recording.wav. I file .mp3, .mpga, .m4a e .aac arrivano come audio che si riproduce nella chat, e msg segue come messaggio di testo separato (l'audio non ha didascalia).

Immagine da un URL
curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "msg_type": 1,
    "country_code": "91",
    "phone": "9876543210",
    "img_url": "https://example.com/offers/diwali-sale.jpg",
    "msg": "Our Diwali sale starts today 🎉"
  }'
Carica un file
curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -F client_id=12345 \
  -F api_key=YOUR_API_KEY \
  -F whatsapp_client=678 \
  -F msg_type=2 \
  -F country_code=91 \
  -F phone=9876543210 \
  -F "msg=Your invoice for order #4821 is attached." \
  -F file_name=invoice-4821.pdf \
  -F file=@./invoice-4821.pdf

Usare i client ufficiali#

I client per Python e Node.js chiamano questo endpoint per te.

from wbiztool_client import WbizToolClient

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

result = client.send_message(
    phone="9876543210",
    country_code="91",
    msg="Hi Aman, your order #4821 has shipped.",
    whatsapp_client=678,
)
print(result)

Gli errori sollevano requests.HTTPError. Leggi il motivo con e.response.json()["message"].

Risposta#

Una richiesta riuscita restituisce HTTP 200:

{
  "status": 1,
  "message": "Created",
  "msg_id": 9817263
}
CampoTipoDescrizione
statusinteger1 se il messaggio è stato messo in coda, 0 se la richiesta non è riuscita.
messagestringCreated in caso di successo, altrimenti l'errore.
msg_idintegerID del messaggio in coda. Salvalo per verificarne lo stato in seguito. Presente solo in caso di successo.

"status": 1 significa che il messaggio è stato messo in coda, non che abbia già raggiunto il destinatario. Usa un webhook o Stato del messaggio per confermare che è stato inviato.

Errori#

Gli errori restituiscono HTTP 400 con status impostato su 0 (Account Disabled non ha il campo status):

{ "status": 0, "message": "Msg cant be null" }
MessaggioCome risolvere
Auth Error - Please send correct API key and Client idInvia un api_key non vuoto.
Invalid client id.Invia client_id come numero.
Auth Error: invalid api keyVerifica che la chiave esista, non sia stata eliminata e appartenga a questo client_id.
Either phone or group_name parameter is requiredAggiungi phone.
Please provide either phone OR group_name, not bothRimuovi uno dei due.
Invalid phone numberphone deve essere un numero da 6 a 17 cifre. Lettere e altri simboli non sono ammessi, e nemmeno un valore arrotondato da foglio di calcolo come 9.19877E+11.
Invalid Contact Number "…"Con il prefisso internazionale aggiunto, il numero deve avere da 7 a 15 cifre.
Msg cant be nullI messaggi di testo (msg_type 0) richiedono msg.
Message length is too longMantieni msg entro i 3.000 caratteri.
Image Url Can't be nullPer msg_type 1, invia img_url o carica un file.
File Url Can't be nullPer msg_type 2, invia file_url o carica un file.
Invalid file url, Can't download / Invalid file urlL'URL non è pubblico, è scaduto il tempo di download oppure il file supera i 100 MB.
Invalid whatsapp clientQuell'ID whatsapp_client non è nel tuo spazio di lavoro.
Invalid whatsapp client id.Invia whatsapp_client. È obbligatorio quando il tuo spazio di lavoro ha più di un numero collegato.
Telegram usernames can only be sent to from a Telegram account: pass its id as whatsapp_clientUn @username, un link t.me o tg:<id> in phone richiede un account Telegram come whatsapp_client.
Not enough creditsLo spazio di lavoro è sul piano gratuito e non ha più messaggi: i piani a pagamento inviano messaggi illimitati. Vedi Quando finiscono i messaggi.
Daily limit reached: a number can send 1,000 messages in 24 hours (fair use). Send the rest tomorrow. (HTTP 429, "code": "daily_limit_reached")Questo numero ha accettato 1.000 messaggi nelle ultime 24 ore (uso corretto). La risposta contiene comunque il msg_id del messaggio rifiutato, che risulta non riuscito. Invia il resto più tardi o da un altro numero.
Demo Account can not access apisUsa un account normale.
Account DisabledIl tuo account è disattivato. Contatta l'assistenza.
Invalid JSON format: …Il corpo JSON non è valido, spesso a causa di una virgola finale o di un a capo non codificato in msg. Usa \n per andare a capo.

Un messaggio in coda può comunque non riuscire al momento dell'invio, ad esempio con File exceeds WhatsApp size limit (…). Questi errori non compaiono mai in questa risposta. Vedi Invio di immagini e file e controlla Stato del messaggio.

Webhook#

Se passi webhook, WbizTool invia una POST a quell'URL quando il messaggio viene inviato o non riesce, e anche quando viene annullato o scade prima di essere stato inviato. Il corpo è codificato come modulo (application/x-www-form-urlencoded), non JSON:

msg_id=9817263&status=SENT
CampoValori
msg_idIl msg_id restituito quando hai inviato il messaggio.
statusSENT, FAILED, CANCELLED (annullato prima dell'invio: con Annulla messaggio, dalla dashboard, oppure perché è stato rimosso il suo numero WhatsApp o la sua campagna) o EXPIRED (non inviato prima che expire_after_seconds scadesse)

Ogni webhook è firmato: gli header WbizTool-Timestamp e WbizTool-Signature (v1= seguito da un HMAC-SHA256 di <timestamp>.<raw body> con il secret di firma del tuo spazio di lavoro) ti permettono di verificare che arrivi da WbizTool. Trovi il secret e la verifica in Python e Node.js in Firme dei webhook; i destinatari che ignorano gli header continuano a funzionare.

Rispondi con un qualsiasi codice 2xx; un reindirizzamento viene seguito, al massimo 3 volte. Se il tuo endpoint non risponde entro 10 secondi, non è raggiungibile o restituisce 429 o 5xx, WbizTool riprova dopo 30 secondi, 1 minuto e 2 minuti (4 tentativi in totale). Le altre risposte 4xx non vengono ritentate. L'URL deve essere un indirizzo pubblico di internet: un webhook verso un indirizzo privato o locale (come 192.168.x.x o localhost) non viene inviato.

Suggerimenti#

  • Numeri di telefono: memorizza i numeri in formato internazionale e inviali con country_code per evitare ambiguità.
  • A capo nel JSON: scrivili come \n all'interno di msg. Un a capo letterale rende il JSON non valido.
  • Mantieni il numero collegato: i messaggi vengono inviati dal tuo numero WhatsApp, quindi deve restare collegato nelle Impostazioni WhatsApp.
  • Molti destinatari: per inviare lo stesso messaggio a più numeri in una sola richiesta, usa Invia a più numeri. Per campagne di grandi dimensioni, carica invece un foglio di calcolo dalla pagina Campagne.