Documentazione API — Inviare messaggi WhatsApp via REST

Introduzione

La Whaiz API ti permette di inviare messaggi WhatsApp dal tuo numero collegato, da qualsiasi linguaggio di programmazione. Tutte le richieste sono HTTPS e usano JSON.

Base URL: https://api.whaiz.info/v1
Il numero da cui invii è determinato dalla tua chiave API (ogni chiave è legata a un numero) — non serve indicarlo nell'URL.
Formato risposta: { "success": true, "data": { … } }

Autenticazione

Ogni richiesta richiede una chiave API. Creala dalla dashboard in API → Crea chiave (la vedi una sola volta). Puoi passarla in due modi:

• Nel corpo JSON come campo token (stile semplice).
• Oppure nell'header Authorization: Bearer <chiave> o x-api-key.

Non esporre mai la chiave in pagine pubbliche lato browser: chiamala da codice lato server.

Il tuo primo invio

Sostituisci token con la tua chiave API. Il numero da cui parte il messaggio è quello legato alla chiave.

curl -X POST "https://api.whaiz.info/v1/messages/text" \
  -H "Content-Type: application/json" \
  -d '{"token":"wha_live_LA_TUA_CHIAVE","to":"393331234567","body":"Ciao!"}'

Inviare un testo

Invia un messaggio di testo semplice.

POST/messages/text

Parametri

Parametro	Tipo	Obblig.	Descrizione
token	string	Sì	La tua chiave API (vedi Autenticazione).
to	string	Sì	Destinatario in formato internazionale (es. 393331234567) oppure un gruppo …@g.us.
body	string	Sì	Il testo del messaggio (max 8000 caratteri).

Esempio di richiesta

curl -X POST "https://api.whaiz.info/v1/messages/text" \
  -H "Content-Type: application/json" \
  -d '{"token":"wha_live_LA_TUA_CHIAVE","to":"393331234567","body":"Ciao dal mio software 👋"}'

Risposta

{
  "success": true,
  "data": {
    "id": "cmq54mvrb001x13oj...",
    "to": "393331234567@c.us",
    "type": "text",
    "status": "sent"
  }
}

Inviare un'immagine

Invia un'immagine scaricata da un URL pubblico (max 16 MB).

POST/messages/image

Parametri

Parametro	Tipo	Obblig.	Descrizione
token	string	Sì	La tua chiave API (vedi Autenticazione).
to	string	Sì	Destinatario in formato internazionale (es. 393331234567) oppure un gruppo …@g.us.
url	string	Sì	URL http(s) dell'immagine.
caption	string	No	Didascalia opzionale.

Esempio di richiesta

curl -X POST "https://api.whaiz.info/v1/messages/image" \
  -H "Content-Type: application/json" \
  -d '{"token":"wha_live_LA_TUA_CHIAVE","to":"393331234567","url":"https://tuosito.com/foto.jpg","caption":"Guarda qui!"}'

Risposta

{
  "success": true,
  "data": {
    "id": "cmq54mvrb001x13oj...",
    "to": "393331234567@c.us",
    "type": "image",
    "status": "sent"
  }
}

Inviare un documento

Invia un file (PDF, ecc.) scaricato da un URL pubblico (max 16 MB).

POST/messages/document

Parametri

Parametro	Tipo	Obblig.	Descrizione
token	string	Sì	La tua chiave API (vedi Autenticazione).
to	string	Sì	Destinatario in formato internazionale (es. 393331234567) oppure un gruppo …@g.us.
url	string	Sì	URL http(s) del file.
filename	string	Sì	Nome file mostrato al destinatario.
caption	string	No	Didascalia opzionale.

Esempio di richiesta

curl -X POST "https://api.whaiz.info/v1/messages/document" \
  -H "Content-Type: application/json" \
  -d '{"token":"wha_live_LA_TUA_CHIAVE","to":"393331234567","url":"https://tuosito.com/documento.pdf","filename":"documento.pdf","caption":"Ecco il file"}'

Risposta

{
  "success": true,
  "data": {
    "id": "cmq54mvrb001x13oj...",
    "to": "393331234567@c.us",
    "type": "document",
    "status": "sent"
  }
}

Inviare una posizione

Invia un pin di posizione geografica.

POST/messages/location

Parametri

Parametro	Tipo	Obblig.	Descrizione
token	string	Sì	La tua chiave API (vedi Autenticazione).
to	string	Sì	Destinatario in formato internazionale (es. 393331234567) oppure un gruppo …@g.us.
latitude	number	Sì	Latitudine (-90…90).
longitude	number	Sì	Longitudine (-180…180).
name	string	No	Nome del luogo.
address	string	No	Indirizzo.

Esempio di richiesta

curl -X POST "https://api.whaiz.info/v1/messages/location" \
  -H "Content-Type: application/json" \
  -d '{"token":"wha_live_LA_TUA_CHIAVE","to":"393331234567","latitude":41.9028,"longitude":12.4964,"name":"Roma","address":"Italia"}'

Risposta

{
  "success": true,
  "data": {
    "id": "cmq54mvrb001x13oj...",
    "to": "393331234567@c.us",
    "type": "location",
    "status": "sent"
  }
}

Inviare un contatto

Invia una scheda contatto (vCard) generata da nome e numero.

POST/messages/contact

Parametri

Parametro	Tipo	Obblig.	Descrizione
token	string	Sì	La tua chiave API (vedi Autenticazione).
to	string	Sì	Destinatario in formato internazionale (es. 393331234567) oppure un gruppo …@g.us.
contactName	string	Sì	Nome del contatto.
contactPhone	string	Sì	Numero del contatto (formato internazionale).

Esempio di richiesta

curl -X POST "https://api.whaiz.info/v1/messages/contact" \
  -H "Content-Type: application/json" \
  -d '{"token":"wha_live_LA_TUA_CHIAVE","to":"393331234567","contactName":"Mario Rossi","contactPhone":"393331112233"}'

Risposta

{
  "success": true,
  "data": {
    "id": "cmq54mvrb001x13oj...",
    "to": "393331234567@c.us",
    "type": "contact",
    "status": "sent"
  }
}

Inviare un audio

Invia un file audio scaricato da un URL pubblico (max 16 MB).

POST/messages/audio

Parametri

Parametro	Tipo	Obblig.	Descrizione
token	string	Sì	La tua chiave API (vedi Autenticazione).
to	string	Sì	Destinatario in formato internazionale (es. 393331234567) oppure un gruppo …@g.us.
url	string	Sì	URL http(s) del file audio (es. mp3).

Esempio di richiesta

curl -X POST "https://api.whaiz.info/v1/messages/audio" \
  -H "Content-Type: application/json" \
  -d '{"token":"wha_live_LA_TUA_CHIAVE","to":"393331234567","url":"https://tuosito.com/audio.mp3"}'

Risposta

{
  "success": true,
  "data": {
    "id": "cmq54mvrb001x13oj...",
    "to": "393331234567@c.us",
    "type": "audio",
    "status": "sent"
  }
}

Stato del numero

Verifica se il numero è connesso a WhatsApp. Il token va in header.

GET/status

curl "https://api.whaiz.info/v1/status" \
  -H "x-api-key: wha_live_LA_TUA_CHIAVE"

Risposta

{
  "success": true,
  "data": {
    "instance": "cmpwquy5c001u...",
    "phoneNumber": "39351...",
    "status": "CONNECTED",
    "connected": true
  }
}

Codici di errore

In caso di errore la risposta è { "success": false, "error": "…" } con uno di questi codici HTTP:

Codice	Significato
400	Parametri non validi (numero/URL/campi mancanti).
401	Token API mancante o non valido/revocato.
402	Abbonamento non attivo, oppure limite numeri raggiunto.
404	Instance non trovata (numero non collegato a questo account).
409	Il numero WhatsApp non è connesso.
413	File troppo grande (max 16 MB).
429	Troppe richieste (rate limit) o coda di invio piena.
502	Invio del messaggio fallito.

Limiti & anti-ban

🛡️ Ritardo anti-ban: gli invii sullo stesso numero vengono distanziati di un intervallo configurabile (minimo 5 secondi) per proteggere l'account WhatsApp dal ban. Imposta il valore dalla pagina API.

⏱️ Rate limit: le richieste sono limitate per utente; in caso di superamento ricevi 429.

📦 Media: i file (immagine/documento/audio) vengono scaricati dall'URL fornito, massimo 16 MB.

💳 Abbonamento: l'invio richiede un abbonamento attivo e rispetta il numero di numeri inclusi nel piano.

Pronto a integrare?

Crea la tua chiave API e copia lo snippet pronto in 11 linguaggi dalla dashboard.