> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mycentralino.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Invia un messaggio

> Manda a un cliente un messaggio WhatsApp di testo o un template

# POST /v1/whatsapp/messages

Manda un messaggio WhatsApp a un cliente, da uno dei numeri collegati a MyFlow. Il messaggio parte come quelli scritti dall'Inbox e compare nella conversazione, segnato come inviato dal gestionale.

Ci sono due tipi di messaggio, e la regola che li separa è di WhatsApp:

| `type` | Quando si può usare |
| - | - |
| `text` | Testo libero, **solo entro 24 ore dall'ultimo messaggio del cliente** (la «finestra di conversazione»). Serve per rispondere a chi ti ha scritto |
| `template` | Un [template approvato](https://docs.mycentralino.com/mycentralino-api/whatsapp-templates-list.md), **sempre**, anche a chi non ti ha mai scritto. Serve per il primo contatto e per scrivere fuori dalla finestra |

Se non sai se la finestra è aperta, guarda `conversation.window_open` nello [storico](https://docs.mycentralino.com/mycentralino-api/whatsapp-conversation-history.md) o nell'ultimo [webhook](https://docs.mycentralino.com/mycentralino-api/whatsapp-webhooks.md). Un `text` a finestra chiusa risponde `409` `window_closed`: in quel caso manda un template.

## Request Body

| Campo | Tipo | Obbligatorio | Descrizione |
| - | - | - | - |
| `type` | string | ✅ | `text` oppure `template` |
| `to` | string | ✅ | Il cliente, in formato +E.164 (es. `+393331234567`). Si accettano anche il prefisso `00` e i numeri italiani senza prefisso (`3331234567` diventa `+393331234567`) |
| `from` | string | dipende | Il numero mittente in formato +E.164, uno di quelli di [GET /v1/whatsapp/numbers](https://docs.mycentralino.com/mycentralino-api/whatsapp-numbers.md). **Obbligatorio** se l'account ha più numeri |
| `text` | string | con `text` | Il testo, da 1 a 4096 caratteri. Può andare a capo |
| `template` | object | con `template` | Il template da inviare (vedi sotto) |

### L'oggetto `template`

| Campo | Tipo | Obbligatorio | Descrizione |
| - | - | - | - |
| `name` | string | ✅ | Il nome del template, com'è nell'[elenco](https://docs.mycentralino.com/mycentralino-api/whatsapp-templates-list.md) |
| `language` | string | dipende | La lingua (es. `it`). **Obbligatorio** se lo stesso template è approvato in più lingue |
| `variables` | object | dipende | I valori delle variabili, con le chiavi dell'elenco (`body.1`, `header.1`, `button.0.1`…). **Obbligatorio** se il template ha variabili: servono tutte, né una di più né una di meno |

Ogni valore di `variables` è una stringa (o un numero) da 1 a 1024 caratteri. A capo e tabulazioni diventano spazi e più di tre spazi di fila si riducono a tre: Meta non li accetta dentro una variabile.

## Header

| Header | Obbligatorio | Descrizione |
| - | - | - |
| `Idempotency-Key` | ❌ (consigliato) | Da 1 a 200 caratteri stampabili, senza spazi, per esempio l'ID dell'invio nel tuo gestionale. Ripetere la chiamata con la stessa chiave non manda un secondo messaggio (vedi sotto) |

## Richiesta

Un template:

```bash cURL theme={null}
curl -X POST "https://api.mycentralino.com/v1/whatsapp/messages" \
  -H "X-API-KEY: sk_mycentralino_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: promemoria-4711" \
  -d '{
      "from": "+390212345678",
      "to": "+393331234567",
      "type": "template",
      "template": {
          "name": "promemoria_appuntamento",
          "language": "it",
          "variables": {
              "body.1": "Mario Rossi",
              "body.2": "giovedì 17 settembre",
              "body.3": "10:00"
          }
      }
  }'
```

```php PHP theme={null}
<?php
$data = [
    'from' => '+390212345678',
    'to' => '+393331234567',
    'type' => 'template',
    'template' => [
        'name' => 'promemoria_appuntamento',
        'language' => 'it',
        'variables' => [
            'body.1' => 'Mario Rossi',
            'body.2' => 'giovedì 17 settembre',
            'body.3' => '10:00'
        ]
    ]
];

$ch = curl_init('https://api.mycentralino.com/v1/whatsapp/messages');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => [
        'X-API-KEY: sk_mycentralino_your_api_key',
        'Content-Type: application/json',
        'Idempotency-Key: promemoria-4711'
    ]
]);
$response = curl_exec($ch);
curl_close($ch);
print_r(json_decode($response, true));
```

```python Python theme={null}
import requests

headers = {'X-API-KEY': 'sk_mycentralino_your_api_key', 'Idempotency-Key': 'promemoria-4711'}
data = {
    "from": "+390212345678",
    "to": "+393331234567",
    "type": "template",
    "template": {
        "name": "promemoria_appuntamento",
        "language": "it",
        "variables": {"body.1": "Mario Rossi", "body.2": "giovedì 17 settembre", "body.3": "10:00"}
    }
}
response = requests.post('https://api.mycentralino.com/v1/whatsapp/messages', headers=headers, json=data)
print(response.json())
```

Un testo, entro le 24 ore:

```json theme={null}
{
  "from": "+390212345678",
  "to": "+393331234567",
  "type": "text",
  "text": "Buongiorno Mario, l'appuntamento è confermato per giovedì alle 10:00."
}
```

## Risposta

`202 Accepted`: WhatsApp ha preso in carico il messaggio. La consegna arriva dopo, con l'evento webhook [`message.status`](https://docs.mycentralino.com/mycentralino-api/whatsapp-webhooks#payload).

```json theme={null}
{
  "success": true,
  "data": {
    "message_id": "wamid.HBgMMzkzMzMxMjM0NTY3FQIAERgSNkQ0RTdBMkM5RjFCOEUzQTQ1AA==",
    "status": "accepted",
    "conversation": {
      "window_open": true,
      "window_expires_at": "2026-09-08T10:42:00+02:00"
    }
  },
  "duplicate": false
}
```

Con una `Idempotency-Key` già usata: `200 OK`, la stessa risposta del primo invio e `"duplicate": true`. Nessun messaggio nuovo parte.

## Campi della risposta

| Campo | Tipo | Descrizione |
| - | - | - |
| `message_id` | string | L'ID WhatsApp del messaggio. È lo stesso `id` che trovi nello [storico](https://docs.mycentralino.com/mycentralino-api/whatsapp-conversation-history.md) e nei [webhook](https://docs.mycentralino.com/mycentralino-api/whatsapp-webhooks.md): usalo per collegare gli stati di consegna |
| `status` | string | Sempre `accepted`: WhatsApp ha accettato il messaggio. Non vuol dire ancora consegnato |
| `conversation` | object \| null | La finestra delle 24 ore con quel cliente, dopo l'invio |
| `conversation.window_open` | bool | `true` se il cliente ha scritto nelle ultime 24 ore, cioè se adesso si può mandare testo libero |
| `conversation.window_expires_at` | string \| null | Quando la finestra si chiude: 24 ore dopo l'ultimo messaggio del cliente, in ISO 8601 con offset. Se è nel passato la finestra è chiusa. `null` se il cliente non ha mai scritto |
| `duplicate` | bool | `true` se la risposta viene da un invio già fatto con la stessa `Idempotency-Key` |

## Idempotency-Key

Se una chiamata va in timeout non sai se il messaggio è partito. Con una `Idempotency-Key` puoi ripeterla senza rischio:

* **Stessa chiave, primo invio riuscito:** ricevi `200` con lo stesso `message_id` e `"duplicate": true`. Nessun messaggio nuovo parte.
* **Stessa chiave, primo invio fallito:** ricevi lo stesso errore del primo tentativo, con `"duplicate": true` dentro `error`. Per riprovare davvero usa una chiave nuova.
* **Stessa chiave mentre il primo invio è ancora in corso:** `409` `idempotency_in_progress`. Aspetta un attimo e ripeti.
* **La chiave identifica l'invio, non il contenuto.** Con la stessa chiave e un body diverso ricevi l'esito del primo invio, e il secondo non parte.
* **Vale per l'account**, non per la singola chiave API, e resta legata all'invio per un anno.
* I controlli sul body (campi mancanti, template sbagliato, variabili) avvengono prima. Una richiesta respinta lì non consuma la chiave.

> [!WARNING]
>
> Una `Idempotency-Key` fuori formato, cioè vuota, con spazi o caratteri non ASCII, oppure più lunga di 200 caratteri, **viene ignorata**. La richiesta parte senza protezione dai doppioni. Usa solo lettere, numeri e simboli come `-`, `_`, `:`.

## Da sapere

* **Opt-out.** Se il cliente ha chiesto di non ricevere messaggi promozionali, scrivendo STOP, i template `MARKETING` verso di lui rispondono `403` `opted_out`. I template `UTILITY` e i messaggi di testo partono comunque.
* **Agente AI.** Un messaggio dal gestionale conta come la risposta di un operatore. Se su quella conversazione risponde un [agente AI](https://docs.mycentralino.com/mycentralino-api/whatsapp-agents-list.md), l'agente si mette da parte per il tempo impostato nell'agente, come quando scrive una persona dall'Inbox.
* **Tetto giornaliero.** Gli invii via API hanno un tetto al giorno per account, che si azzera a mezzanotte, ora italiana. Gli invii non riusciti non contano. Oltre il tetto la risposta è `429` `daily_send_limit`. Per scrivere a molti clienti insieme usa le [Campagne](https://docs.mycentralino.com/mycentralino-api/whatsapp-campaigns-create.md), fatte apposta.
* **Template senza file.** L'API per ora non allega file: i template con un'immagine, un video o un documento nell'intestazione rispondono `template_not_usable`. Vale lo stesso per caroselli e offerte a tempo.
* **Costi di Meta.** L'invio di un template può avere un costo di Meta, secondo il listino di Meta e la categoria del template. Il testo libero dentro la finestra delle 24 ore non ha costi di Meta.

## Errori

### 400 - invalid\_type

`type` manca o non è `text` né `template`.

### 400 - invalid\_phone

`to` manca o non è un numero di telefono valido.

### 400 - invalid\_text · 422 - invalid\_text

Con `type` `text`: `400` se `text` manca o non è una stringa, `422` se dopo la pulizia è vuoto o supera i 4096 caratteri.

### 400 - invalid\_template

Con `type` `template`: manca l'oggetto `template` o il suo `name`.

### 422 - template\_not\_found

Nessun template con quel nome sull'account WhatsApp Business del numero. L'elenco è in [GET /v1/whatsapp/templates](https://docs.mycentralino.com/mycentralino-api/whatsapp-templates-list.md).

### 422 - template\_not\_approved

Il template esiste ma non è approvato. Il messaggio dice lo stato, es. «Il template non è approvato da Meta (stato: PENDING).».

### 422 - template\_language\_required

Il template è approvato in più lingue e manca `language`. `error.languages` elenca le lingue.

### 422 - template\_not\_usable

Il template non si può inviare via API: intestazione con un file, carosello, offerta a tempo, posizione o bottoni di un tipo non gestito. Il messaggio dice perché.

### 422 - template\_variables

Le variabili non corrispondono al template. La risposta dice cosa correggere:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "template_variables",
    "message": "Le variabili non corrispondono al template.",
    "expected": ["body.1", "body.2", "body.3"],
    "missing": ["body.3"],
    "unknown": ["body.4"]
  }
}
```

| Campo | Contenuto |
| - | - |
| `expected` | Tutte le chiavi che il template vuole, sempre presente |
| `missing` | Le chiavi mancanti o con un valore che non è testo né numero |
| `unknown` | Le chiavi che il template non ha |
| `invalid` | Le chiavi con un valore vuoto o oltre i 1024 caratteri |

Lo stesso codice, senza questi campi, arriva se `variables` non è un oggetto.

### 403 - opted\_out

Il cliente ha chiesto di non ricevere messaggi promozionali (STOP), e il template è `MARKETING`.

### 409 - window\_closed

Con `type` `text`: il cliente non ti ha mai scritto da questo numero, oppure sono passate più di 24 ore dal suo ultimo messaggio. `error.needs_template` è `true`: manda un template.

```json theme={null}
{
  "success": false,
  "error": {
    "code": "window_closed",
    "message": "Sono passate più di 24 ore dall'ultimo messaggio del contatto: per scrivergli serve un template.",
    "needs_template": true
  }
}
```

### 409 - idempotency\_in\_progress

Un invio con la stessa `Idempotency-Key` è ancora in corso.

### 429 - daily\_send\_limit

Raggiunto il tetto giornaliero di invii via API dell'account. Riprova dopo mezzanotte, oppure usa le Campagne.

### 502 - meta\_error

WhatsApp ha rifiutato l'invio. Il messaggio è la spiegazione in italiano dell'errore di WhatsApp. `error.meta_code` è il codice originale di Meta, es. `131026` (il numero non è su WhatsApp) o `131047` (finestra di 24 ore chiusa). Il messaggio non è partito.

### 400 - number\_required / invalid\_from · 404 - number\_not\_found

`from` manca con più numeri, non è valido o non è collegato all'account. Vedi l'[elenco dei template](https://docs.mycentralino.com/mycentralino-api/whatsapp-templates-list.md#errori).

Gli errori comuni a tutte le rotte sono nell'[introduzione](https://docs.mycentralino.com/mycentralino-api/whatsapp-introduction.md#codici-di-errore).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.