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.
https://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."
}'import requests
response = requests.post(
"https://wbiztool.com/api/v1/send_msg/",
json={
"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.",
},
timeout=60,
)
result = response.json() # read the body even when the HTTP code is 400
if result.get("status") == 1:
print("Queued with msg_id", result["msg_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/send_msg/", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
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.",
}),
});
const result = await response.json(); // read the body even when the HTTP code is 400
if (result.status === 1) {
console.log("Queued with msg_id", result.msg_id);
} else {
console.error("Failed:", result.message);
}<?php
$payload = [
'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.',
];
$ch = curl_init('https://wbiztool.com/api/v1/send_msg/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['status'] ?? 0) === 1) {
echo 'Queued with msg_id ' . $result['msg_id'];
} else {
echo 'Failed: ' . ($result['message'] ?? 'no response');
}Sostituisci 12345, YOUR_API_KEY e 678 con i tuoi valori. Consulta Autenticazione per sapere dove trovarli.
Parametri della richiesta#
Autenticazione
client_idintegerobbligatorioIl tuo ID Client API, da Impostazioni → Chiavi API.
api_keystringobbligatorioLa tua chiave API, dalla stessa pagina.
whatsapp_clientintegerObbligatorio se hai più di un numeroID 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
phonestringobbligatorioIl numero WhatsApp del destinatario, solo cifre. Spazi,
+,-,.e parentesi vengono rimossi automaticamente. Invia il numero con il prefisso internazionale (919876543210) oppure senza (9876543210) insieme acountry_code. Con i campi di un modulo, non includere lo0iniziale del prefisso nazionale (09876543210): non viene rimosso prima che venga aggiuntocountry_code, quindi il messaggio arriva al numero sbagliato. Le richieste JSON lo rimuovono automaticamente.country_codestringfacoltativoPrefisso internazionale senza
+, ad esempio91per l'India o1per gli USA. Viene aggiunto davanti aphone, a meno che il numero non inizi già con esso. Eccezione: con91, 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_typeintegerfacoltativo0testo (predefinito),1immagine,2file o documento.msgstringObbligatorio quando msg_type è 0Testo 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 fileURL pubblico
httpohttpsdell'immagine.file_urlstringObbligatorio quando msg_type è 2 e non viene caricato alcun fileURL pubblico
httpohttpsda cui il file può essere scaricato direttamente.filefilefacoltativoCarica l'immagine o il file invece di fornire un URL. Invia la richiesta come
multipart/form-datacon il campo chiamatofile.file_namestringfacoltativoNome 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_secondsintegerfacoltativoSegna il messaggio come scaduto (stato
4) se non è stato inviato entro questo numero di secondi, ad esempio3600per 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.webhookstringfacoltativoURL che riceve una
POSTquando 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:
httpohttps, 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:
| Problema | error in Stato del messaggio |
|---|---|
Un'immagine (msg_type 1) oltre 16 MB | File exceeds WhatsApp size limit (16MB max) |
Un video (.mp4, .webm) oltre 64 MB, oppure un file vuoto | File 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.
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 🎉"
}'import requests
response = requests.post(
"https://wbiztool.com/api/v1/send_msg/",
json={
"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 🎉",
},
timeout=60,
)
print(response.json())// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v1/send_msg/", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
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 🎉",
}),
});
console.log(await response.json());<?php
$ch = curl_init('https://wbiztool.com/api/v1/send_msg/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'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 🎉',
]),
CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);
curl_close($ch);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.pdfimport requests
with open("invoice-4821.pdf", "rb") as f:
response = requests.post(
"https://wbiztool.com/api/v1/send_msg/",
data={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"whatsapp_client": 678,
"msg_type": 2,
"country_code": "91",
"phone": "9876543210",
"msg": "Your invoice for order #4821 is attached.",
"file_name": "invoice-4821.pdf",
},
files={"file": f},
timeout=120,
)
print(response.json())// Node.js 20+ (built-in fetch, FormData and fs.openAsBlob). Save as .mjs to use top-level await.
import { openAsBlob } from "node:fs";
const form = new FormData();
form.append("client_id", "12345");
form.append("api_key", "YOUR_API_KEY");
form.append("whatsapp_client", "678");
form.append("msg_type", "2");
form.append("country_code", "91");
form.append("phone", "9876543210");
form.append("msg", "Your invoice for order #4821 is attached.");
form.append("file_name", "invoice-4821.pdf");
form.append("file", await openAsBlob("./invoice-4821.pdf"), "invoice-4821.pdf");
// Don't set Content-Type yourself; fetch adds the multipart boundary.
const response = await fetch("https://wbiztool.com/api/v1/send_msg/", { method: "POST", body: form });
console.log(await response.json());<?php
$ch = curl_init('https://wbiztool.com/api/v1/send_msg/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
// An array body (not json_encode) makes cURL send multipart/form-data.
CURLOPT_POSTFIELDS => [
'client_id' => 12345,
'api_key' => 'YOUR_API_KEY',
'whatsapp_client' => 678,
'msg_type' => 2,
'country_code' => '91',
'phone' => '9876543210',
'msg' => 'Your invoice for order #4821 is attached.',
'file_name' => 'invoice-4821.pdf',
'file' => new CURLFile('/path/to/invoice-4821.pdf', 'application/pdf', 'invoice-4821.pdf'),
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 120,
]);
echo curl_exec($ch);
curl_close($ch);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"].
const { WbizToolClient } = require("wbiztool-client");
const client = new WbizToolClient({
clientId: 12345,
apiKey: "YOUR_API_KEY",
whatsappClient: 678,
});
(async () => {
// Errors throw, with the API's response in the error message.
const result = await client.sendMessage({
phone: "9876543210",
countryCode: "91",
message: "Hi Aman, your order #4821 has shipped.",
});
console.log(result);
})().catch(console.error);Risposta#
Una richiesta riuscita restituisce HTTP 200:
{
"status": 1,
"message": "Created",
"msg_id": 9817263
}
| Campo | Tipo | Descrizione |
|---|---|---|
status | integer | 1 se il messaggio è stato messo in coda, 0 se la richiesta non è riuscita. |
message | string | Created in caso di successo, altrimenti l'errore. |
msg_id | integer | ID 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" }
| Messaggio | Come risolvere |
|---|---|
Auth Error - Please send correct API key and Client id | Invia un api_key non vuoto. |
Invalid client id. | Invia client_id come numero. |
Auth Error: invalid api key | Verifica che la chiave esista, non sia stata eliminata e appartenga a questo client_id. |
Either phone or group_name parameter is required | Aggiungi phone. |
Please provide either phone OR group_name, not both | Rimuovi uno dei due. |
Invalid phone number | phone 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 null | I messaggi di testo (msg_type 0) richiedono msg. |
Message length is too long | Mantieni msg entro i 3.000 caratteri. |
Image Url Can't be null | Per msg_type 1, invia img_url o carica un file. |
File Url Can't be null | Per msg_type 2, invia file_url o carica un file. |
Invalid file url, Can't download / Invalid file url | L'URL non è pubblico, è scaduto il tempo di download oppure il file supera i 100 MB. |
Invalid whatsapp client | Quell'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 credits | Il tuo piano non ha più messaggi disponibili. |
Demo Account can not access apis | Usa un account normale. |
Account Disabled | Il 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
| Campo | Valori |
|---|---|
msg_id | Il msg_id restituito quando hai inviato il messaggio. |
status | SENT 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_codeper evitare ambiguità. - A capo nel JSON: scrivili come
\nall'interno dimsg. 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.
