Vai al contenuto
Wbiztool

API di messaggistica

API Invia messaggio a un gruppo WhatsApp

Invia un testo, un'immagine o un documento WhatsApp a un gruppo WhatsApp di cui fa parte il tuo numero collegato. Usala per annunci al team, aggiornamenti per la community e notifiche broadcast.

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

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

Il messaggio viene messo in coda e inviato al gruppo dal tuo numero WhatsApp. 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/group/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "msg_type": 0,
    "group_name": "Sales Team Mumbai",
    "msg": "Reminder: *weekly review* starts at 4 PM today."
  }'

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 il proprietario ha più di un numero collegato

ID del numero WhatsApp da cui inviare, dalle Impostazioni WhatsApp. Deve essere un numero che appartiene al proprietario dello spazio di lavoro. Se lo ometti e il proprietario ha esattamente un numero collegato, viene usato quel numero.

Gruppo e messaggio

group_namestringobbligatorio

Nome del gruppo WhatsApp, scritto esattamente come appare in WhatsApp. Invialo come stringa. Un numero JSON come 2024 restituisce una pagina di errore HTML (HTTP 500). Vedi Come viene trovato il gruppo.

msg_typeintegerfacoltativo

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

msgstringObbligatorio quando msg_type è 0

Testo del messaggio. 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 gruppo, ad esempio price-list.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. 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. Il payload è lo stesso di Invia messaggio.

Immagini e file seguono le stesse regole di Invia messaggio: gli URL vengono scaricati quando chiami l'API (fino a 100 MB). Al momento dell'invio, le immagini oltre 16 MB e i video oltre 64 MB non riescono, l'audio WAV e OGG non è supportato, e ai file (msg_type 2) senza un'estensione supportata viene aggiunto .pdf, compresi quelli caricati. I nomi dei file vengono inviati in minuscolo. Consulta Invio di immagini e file per l'elenco completo delle estensioni e degli errori.

Per caricare un file, usa gli esempi multipart di Invia messaggio, sostituendo l'URL con /api/v1/send_msg/group/ e phone/country_code con group_name.

Immagine da un URL
curl -X POST https://wbiztool.com/api/v1/send_msg/group/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "msg_type": 1,
    "group_name": "Sales Team Mumbai",
    "img_url": "https://example.com/reports/weekly-sales.png",
    "msg": "This week'\''s sales summary"
  }'

Come viene trovato il gruppo#

Wbiztool non controlla il nome del gruppo quando chiami l'API. Al momento dell'invio del messaggio, Wbiztool cerca group_name nelle tue chat WhatsApp e apre il primo risultato. Di conseguenza:

  • Il tuo numero WhatsApp collegato deve essere membro del gruppo.
  • Usa il nome completo del gruppo esattamente come lo mostra WhatsApp, emoji e punteggiatura compresi. Gli spazi all'inizio e alla fine vengono ignorati.
  • Assicurati che il nome sia univoco. Un nome breve o parziale può corrispondere a un'altra chat che compare prima nella ricerca.
  • Se non c'è alcuna corrispondenza, se nel gruppo solo gli amministratori possono inviare messaggi e il tuo numero non è amministratore, oppure se solo gli amministratori della community possono pubblicare, il messaggio non riesce con l'errore Group not found.
  • Se il tuo numero ha lasciato il gruppo, il messaggio non riesce con l'errore Group member blocked.

I problemi relativi al gruppo non compaiono nella risposta dell'API. Usa un webhook o Stato del messaggio per sapere se il messaggio è stato inviato.

Usare il client ufficiale#

Il client Python chiama questo endpoint per te.

Python
from wbiztool_client import WbizToolClient

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

result = client.send_message_to_group(
    group_name="Sales Team Mumbai",
    msg="Reminder: weekly review starts at 4 PM today.",
    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 raggiunto il gruppo. Usa un webhook o Stato del messaggio per confermare che è stato inviato.

Errori#

Gli errori restituiscono HTTP 400 con status impostato su 0:

{ "status": 0, "message": "Group Name 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.
Group Name cant be nullAggiungi group_name.
Msg cant be nullI messaggi di testo (msg_type 0) richiedono msg.
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 client NoneQuell'ID whatsapp_client non appartiene al proprietario dello spazio di lavoro. Vedi l'avviso sopra.
Invalid whatsapp client id.Invia whatsapp_client. È obbligatorio a meno che il proprietario non abbia esattamente 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.

Suggerimenti#

  • Prova prima il nome: invia un breve testo al gruppo e controlla Stato del messaggio prima di automatizzare qualsiasi cosa.
  • Gruppi rinominati: se qualcuno rinomina il gruppo in WhatsApp, aggiorna anche group_name nella tua integrazione.
  • Tipi di messaggio: gli unici valori validi per msg_type sono 0, 1 e 2. Qualsiasi valore che non sia un numero intero restituisce una pagina di errore HTML (HTTP 500) invece di JSON.
  • Più gruppi insieme: Invia a più numeri accetta nomi di gruppi insieme a numeri di telefono in un'unica richiesta.