# Inviare messaggi

URL: https://wa.genuka.com/it/docs/messages
Language: Italian

> Un solo endpoint che copre tutta la superficie della Cloud API.

```http
POST /api/v1/messages
```

Un invio contiene sempre tre cose: la connessione da cui inviare, il destinatario ed **esattamente
un campo di contenuto**.

```json
{
  "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

> [!WARNING]
> **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

```json
{
  "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.

```json
{
  "connectionId": "cnx_...",
  "to": "+237699001122",
  "template": {
    "name": "order_confirmation",
    "language": "en",
    "body": ["Awa", "ORD-1042"]
  }
}
```

> [!NOTE]
> 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:

```json
{
  "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   |
