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 "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "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 12345, YOUR_API_KEY e 678 con i tuoi valori. Consulta Autenticazione per sapere dove trovarli.

Parametri della richiesta#

Autenticazione

client_idintegerobbligatorio

Il tuo ID Client API, da Impostazioni → Chiavi API.

api_keystringobbligatorio

La tua chiave API, dalla stessa pagina.

whatsapp_clientintegerObbligatorio se hai più di un numero

ID del numero WhatsApp da cui inviare, dalle Impostazioni WhatsApp. Se lo ometti e il tuo spazio di lavoro ha esattamente un numero collegato, viene usato quel numero.

Destinatario e messaggio

phonestringobbligatorio

Il numero WhatsApp del destinatario, solo cifre. Spazi, +, -, . e parentesi vengono rimossi automaticamente. Invia il numero con il prefisso internazionale (919876543210) oppure senza (9876543210) insieme a country_code. Con i campi di un modulo, non includere lo 0 iniziale del prefisso nazionale (09876543210): non viene rimosso prima che venga aggiunto country_code, quindi il messaggio arriva al numero sbagliato. Le richieste JSON lo rimuovono automaticamente.

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. 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 o non riesce. 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.

Estensioni supportate: .pdf, .xlsx, .xls, .txt, .docx, .png, .jpg, .jpeg, .webp, .mp3, .mpga, .m4a, .mp4, .webm.

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, oppure un file vuotoFile exceeds WhatsApp size limit (…)
Un file .ogg, oppure un file .wav inviato come immagine (msg_type 1)File type not supported

L'audio WAV e OGG non è supportato. Un file .wav inviato come file (msg_type 2) non viene rifiutato, ma arriva come recording.wav.pdf. Converti prima l'audio in .mp3 o .m4a.

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 contenere solo cifre (da 6 a 17), eventualmente precedute da +.
Invalid Contact Number "…"Con il prefisso internazionale aggiunto, il numero deve avere da 6 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.
Not enough creditsIl tuo piano non ha più messaggi disponibili.
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. 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 o FAILED

Rispondi con un qualsiasi codice 2xx. Se il tuo endpoint va in timeout (dopo 3 secondi) o restituisce 5xx, la chiamata viene ritentata fino a 3 volte in totale. Una risposta 4xx non viene ritentata. Nessun webhook viene inviato quando un messaggio viene annullato o scade: in questi casi usa Stato del messaggio.

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.