Inviare messaggi
Un solo endpoint che copre tutta la superficie della Cloud API.
POST /api/v1/messagesUn invio contiene sempre tre cose: la connessione da cui inviare, il destinatario ed esattamente un campo di contenuto.
{
"connectionId": "cnx_...",
"to": "+237699001122",
"text": "Hello 👋"
}Il numero è in formato internazionale. Ottieni connectionId da GET /api/v1/connections.
Aggiungi replyTo con il wamid di un messaggio in arrivo per citarlo nella tua risposta.
Campi di contenuto
Un campo alla volta
Inviare due campi di contenuto nella stessa richiesta non invia due messaggi: viene usato solo il primo riconosciuto. Fai due chiamate.
Testo e media
| Campo | Contenuto | Limiti |
|---|---|---|
text | Una stringa, oppure { body, previewUrl } | 4096 caratteri |
image | JPEG, PNG | 5 MB, didascalia di 1024 caratteri |
video | MP4, 3GPP (H.264 + AAC) | 16 MB |
audio | AAC, AMR, MP3, M4A, OGG | 16 MB, nessuna didascalia |
document | PDF, DOC(X), XLS(X), PPT(X), TXT | 100 MB |
sticker | WebP statico o animato | 100 KB / 500 KB |
Posizione, contatti, reazione
| Campo | Contenuto |
|---|---|
location | { latitude, longitude, name, address } |
locationRequest | { body } — mostra un pulsante "Invia posizione" |
contacts | Un array di schede contatto |
reaction | { messageId, emoji } — una stringa vuota rimuove la reazione |
Messaggi interattivi
{
"connectionId": "cnx_...",
"to": "+237699001122",
"buttons": {
"body": "How can we help?",
"footer": "Genuka",
"buttons": [
{ "id": "order", "title": "My order" },
{ "id": "support", "title": "A problem" }
]
}
}| Campo | Descrizione | Limiti |
|---|---|---|
buttons | Pulsanti di risposta rapida | 3 al massimo, titoli di 20 caratteri |
list | Sezioni e righe | 10 sezioni, 10 righe in totale |
cta | Un unico pulsante con un URL | url + displayText |
La risposta dell'utente arriva via webhook, con l'id del pulsante o della riga che ha scelto.
Modelli
Fuori dalla finestra di 24 ore, verrà consegnato solo un modello approvato.
{
"connectionId": "cnx_...",
"to": "+237699001122",
"template": {
"name": "order_confirmation",
"language": "en",
"body": ["Awa", "ORD-1042"]
}
}L'invio di un modello apre una conversazione Meta a pagamento sulla WABA del cliente stesso: Meta fattura direttamente il cliente. I messaggi di servizio inviati all'interno della finestra di 24 ore sono gratuiti.
Crea e segui i modelli tramite /api/v1/templates. Un modello in stato PAUSED o REJECTED non
può essere usato: controlla il suo stato prima di lanciare una campagna.
Via di fuga
Se un tipo di messaggio non è ancora esposto, raw inoltra così com'è un frammento della Cloud API:
{
"connectionId": "cnx_...",
"to": "+237699001122",
"raw": { "type": "interactive", "interactive": { "type": "flow" } }
}Su raw non viene applicata alcuna validazione: gli errori tornano da Meta così come sono.
Errori comuni
| Codice Meta | Significato | Cosa fare |
|---|---|---|
131047 | Più di 24 h dall'ultimo messaggio in arrivo | Invia un modello |
131026 | Destinatario irraggiungibile o non su WhatsApp | Non riprovare |
131050 | L'utente si è disiscritto dal marketing | Non inviargli mai più marketing |
131049 | Raggiunto il limite di marketing per utente | Riprova più tardi |
132001 | Modello inesistente o non approvato in quella lingua | Controlla nome e lingua |
130429 | Velocità di invio superata | Rallenta, riprova con backoff |