> ## 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.

# Aggiungi destinatari

> Aggiunge i destinatari a una bozza di campagna, a blocchi, con i valori per destinatario

# POST /v1/whatsapp/campaigns/\{id}/recipients

Aggiunge destinatari a una campagna in **bozza**. Si chiama più volte, a blocchi di fino a **1000 destinatari**, fino a un massimo di **10.000 per campagna**. Dopo il lancio l'elenco non si modifica più.

La chiamata si può ripetere senza problemi: un numero già presente nella campagna non si duplica, vale la prima volta che l'hai mandato. Se un blocco va in errore di rete, rimandalo intero.

## Parametri

| Parametro | Tipo | Obbligatorio | Descrizione |
| - | - | - | - |
| `id` | int | ✅ | ID della campagna (nel percorso) |

## Request Body

| Campo | Tipo | Obbligatorio | Descrizione |
| - | - | - | - |
| `recipients` | array | ✅ | Da 1 a 1000 destinatari |

Ogni destinatario:

| Campo | Tipo | Obbligatorio | Descrizione |
| - | - | - | - |
| `phone` | string | ✅ | Il numero WhatsApp del cliente. Meglio in formato `+E.164` (`+393331234567`). Si accettano anche `0039…`, un cellulare italiano senza prefisso (`3331234567`) e un fisso italiano senza prefisso (`0212345678`), che diventano `+39…` |
| `name` | string | ❌ | Nome del destinatario, fino a 120 caratteri (oltre viene tagliato). Si vede nel pannello, nell'elenco dei destinatari della campagna. **Non** riempie da solo le variabili del messaggio |
| `variables` | object | ❌ | I valori per destinatario: `{"body.1": "Mario"}`. Solo per le variabili che nella bozza hai indicato con `"per_recipient": true`. Ogni valore fino a 200 caratteri. Se manca o è vuoto si usa il `fallback` della bozza |

> [!WARNING]
>
> Il body di una richiesta non può superare **64 KB**. Mille destinatari con il solo telefono ci stanno; con nome e variabili un blocco da 1000 può superare il limite e ricevere `413 body_too_large`. In quel caso usa blocchi da 500.

## Richiesta

```bash cURL theme={null}
curl -X POST "https://api.mycentralino.com/v1/whatsapp/campaigns/48/recipients" \
  -H "X-API-KEY: sk_mycentralino_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
      "recipients": [
          {"phone": "+393331234567", "name": "Mario Rossi", "variables": {"body.1": "Mario"}},
          {"phone": "+393337654321", "name": "Giulia Bianchi", "variables": {"body.1": "Giulia"}},
          {"phone": "+393401112223"},
          {"phone": "12345"}
      ]
  }'
```

```php PHP theme={null}
<?php
$data = [
    'recipients' => [
        ['phone' => '+393331234567', 'name' => 'Mario Rossi', 'variables' => ['body.1' => 'Mario']],
        ['phone' => '+393337654321', 'name' => 'Giulia Bianchi', 'variables' => ['body.1' => 'Giulia']],
        ['phone' => '+393401112223'],
        ['phone' => '12345']
    ]
];

$ch = curl_init('https://api.mycentralino.com/v1/whatsapp/campaigns/48/recipients');
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'
    ]
]);
$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'}
data = {"recipients": [
    {"phone": "+393331234567", "name": "Mario Rossi", "variables": {"body.1": "Mario"}},
    {"phone": "+393337654321", "name": "Giulia Bianchi", "variables": {"body.1": "Giulia"}},
    {"phone": "+393401112223"},
    {"phone": "12345"}
]}
response = requests.post('https://api.mycentralino.com/v1/whatsapp/campaigns/48/recipients', headers=headers, json=data)
print(response.json())
```

Con molti contatti, manda blocchi uno dopo l'altro:

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

headers = {'X-API-KEY': 'sk_mycentralino_your_api_key'}
url = 'https://api.mycentralino.com/v1/whatsapp/campaigns/48/recipients'
# clienti = l'elenco dal tuo gestionale: [{"telefono": "+393331234567", "nome": "Mario"}, ...]

for i in range(0, len(clienti), 500):
    blocco = [{"phone": c["telefono"], "name": c["nome"], "variables": {"body.1": c["nome"]}}
              for c in clienti[i:i + 500]]
    r = requests.post(url, headers=headers, json={"recipients": blocco}).json()
    print(r["data"]["added"], "aggiunti,", r["data"]["total"], "in tutto")
```

## Risposta

`200 OK`

```json theme={null}
{
  "success": true,
  "data": {
    "added": 2,
    "already": 0,
    "stopped": 1,
    "over": 0,
    "invalid": [
      {"index": 3, "reason": "numero non valido"}
    ],
    "total": 3,
    "sendable": 2,
    "max": 10000
  }
}
```

In questo esempio Mario e Giulia sono stati aggiunti, il terzo numero aveva chiesto di non ricevere promozioni ed è entrato come escluso, il quarto è stato scartato.

## Campi della risposta

| Campo | Tipo | Descrizione |
| - | - | - |
| `added` | int | Destinatari aggiunti con questa chiamata, che riceveranno il messaggio |
| `already` | int | Numeri già presenti nella campagna, o ripetuti nello stesso blocco: ignorati |
| `stopped` | int | Numeri che hanno chiesto di non ricevere promozioni (STOP) dai tuoi numeri WhatsApp: entrano nella campagna come esclusi, non ricevono niente e restano visibili nel resoconto |
| `over` | int | Numeri non aggiunti perché la campagna ha già 10.000 destinatari |
| `invalid` | array | Destinatari scartati, con la posizione nel blocco (`index`, da 0) e il motivo (`reason`) |
| `total` | int | Destinatari della campagna dopo questa chiamata, esclusi compresi |
| `sendable` | int | Destinatari a cui la campagna invierà: è il numero che conta al lancio |
| `max` | int | Il massimo di destinatari per campagna |

### Motivi di scarto (`invalid[].reason`)

| `reason` | Cosa correggere |
| - | - |
| `numero non valido` | `phone` manca o non è un numero riconoscibile |
| `formato non valido` | Il destinatario non è un oggetto JSON |
| `"variables" deve essere un oggetto` | `variables` è una lista o un valore semplice |
| `variabile «…» non prevista per destinatario` | Quella chiave nella bozza non ha `"per_recipient": true`, oppure il template non la ha |
| `valore di «…» non valido` | Il valore non è un testo o un numero |
| `valore di «…» oltre 200 caratteri` | Accorcia il valore |
| `valori troppo lunghi` | L'insieme dei valori di quel destinatario è troppo lungo: accorcia i testi |

Un destinatario scartato non blocca gli altri: correggilo e rimandalo in un'altra chiamata.

> [!NOTE]
>
> Chi ha chiesto di non ricevere più promozioni viene escluso anche se l'hai mandato: non serve filtrarlo prima. Al momento dell'invio la campagna ricontrolla gli STOP e la regola **Limite per contatto** (in MyFlow → **Impostazioni** → **Regole di invio**): chi ha già ricevuto una promozione nei giorni indicati viene saltato.

## Errori

### 404 - campaign\_not\_found

Non c'è una campagna con questo `id` su questo account.

### 409 - campaign\_not\_draft

La campagna è già stata lanciata, o annullata: i destinatari si aggiungono solo a una bozza.

### 422 - invalid\_recipients

`recipients` manca, è vuoto, non è una lista o ha più di 1000 elementi.

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.