# Riferimento dell'API

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

> Una sola API per gestire tutto in modo programmatico: numeri, modelli, messaggi, campagne e il tuo abbonamento.

Costruisci il tuo prodotto sopra di essa.

> [!NOTE]
> **Specifica OpenAPI**
>
> L'intera API è descritta in OpenAPI 3.1 su
> [`https://wa.genuka.com/openapi.json`](https://wa.genuka.com/openapi.json): importala in
> Postman o Insomnia, oppure passala a un agente di programmazione AI. Per gli agenti,
> [`/llms.txt`](https://wa.genuka.com/llms.txt) indicizza tutta la documentazione.

## Autenticazione

Tutte le richieste usano una chiave API lato server. Generane una nella tua dashboard, in **Chiavi
API**: ha la forma `pk_live_…` e viene mostrata una sola volta. Inviala come bearer token:

```http title="Header"
Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

> [!WARNING]
> **Tieni le chiavi lato server**
>
> Una chiave può inviare messaggi da tutti i numeri che copre. Non esporla mai in un browser o in
> un'app mobile: chiama l'API solo dal tuo backend.

### Ambito della chiave

Una chiave vale per tutto l'account oppure è legata a una sola azienda collegata. Scegli l'azienda
quando generi la chiave in **Chiavi API**. Una chiave con ambito ristretto risolve solo quell'azienda:
le liste restituiscono solo le sue righe, gli id che appartengono a un'altra rispondono `404` e
`GET /api/v1/subscription` risponde 403; così puoi consegnarla a quell'azienda (o gestire la sua
integrazione) senza esporre il resto del tuo account. Le chiavi a livello di account raggiungono
tutti i numeri che hai collegato.

## Convenzioni

URL di base `https://wa.genuka.com/api/v1`. Corpi e risposte sono in JSON. Gli endpoint di elenco
restituiscono `{ "data": [...] }`. Tutto è automaticamente limitato al tuo account. Gli errori usano
i codici di stato HTTP con `{ "error": "code", "message": "…" }`.

Chiama `wa.genuka.com` in **https** e senza slash finale: `http://` restituisce un `301` verso https,
`/api/v1/messages/` un `308` verso la forma senza slash, e alcuni client HTTP scartano l'header
`Authorization` quando seguono un reindirizzamento. Nessun altro hostname serve questa API.

> [!WARNING]
> **Invia uno User-Agent**
>
> La nostra CDN rifiuta alcune firme di bot note prima che raggiungano l'API. Quella in cui i nostri
> integratori incappano più spesso è `Python-urllib/3.x`, l'header che `urllib` invia di default:
> risponde `403` con il corpo `error code: 1010`, che non proviene da noi e quindi non contiene
> JSON. Invia uno `User-Agent` che identifichi la tua integrazione, che è comunque ciò che ti
> permetterà di ritrovarti nei tuoi log:
>
> ```python
> request.add_header("User-Agent", "acme-crm/1.4 (+https://example.com)")
> ```
>
> `requests`, `curl`, `axios`, `node-fetch` e i client Go e Java passano senza modifiche.

## Aziende (attività collegate)

| Metodo | Endpoint                 | Descrizione                                         |
| ------ | ------------------------ | --------------------------------------------------- |
| `GET`  | `/api/v1/companies`      | Elenca le aziende collegate con le loro connessioni |
| `GET`  | `/api/v1/companies/{id}` | Una singola azienda + connessioni + conteggi        |

```bash title="GET /api/v1/companies"
curl https://wa.genuka.com/api/v1/companies -H "Authorization: Bearer pk_live_xxx"

{
  "data": [
    {
      "id": "cmp_123",
      "name": "Acme Coffee",
      "onboardedAt": "2026-06-01T10:12:00.000Z",
      "connections": [
        { "id": "con_1", "wabaId": "1029…", "phoneNumberId": "1065…",
          "displayPhoneNumber": "+237 6 90 …", "qualityRating": "GREEN", "status": "connected" }
      ],
      "_count": { "templates": 4 }
    }
  ]
}
```

## Connessioni (numeri)

| Metodo | Endpoint              | Descrizione                                                                 |
| ------ | --------------------- | --------------------------------------------------------------------------- |
| `GET`  | `/api/v1/connections` | Elenca le connessioni WhatsApp (facoltativi `?companyId=`, `?externalRef=`) |

Una connessione è una WABA + un numero di telefono. Il suo `id` è ciò che passi quando crei modelli,
campagne o invii messaggi.

## Modelli

I modelli sono formati di messaggio pre-approvati. Ne serve uno per *avviare* una conversazione
(cioè scrivere a un cliente fuori dalla finestra di 24 ore; vedi [Messaggi](#messaggi)). Crei un
modello qui, Meta lo revisiona, e l'approvazione o il rifiuto arriva automaticamente su
`GET /templates/{id}` (e sui tuoi [webhook](https://wa.genuka.com/it/docs/webhooks)).

| Metodo   | Endpoint                 | Descrizione                                  |
| -------- | ------------------------ | -------------------------------------------- |
| `GET`    | `/api/v1/templates`      | Elenca i modelli (facoltativo `?companyId=`) |
| `POST`   | `/api/v1/templates`      | Crea e invia un modello a Meta               |
| `GET`    | `/api/v1/templates/{id}` | Un modello + la cronologia dei suoi stati    |
| `POST`   | `/api/v1/templates/sync` | Rilegge tutti gli stati da Meta              |
| `DELETE` | `/api/v1/templates/{id}` | Elimina su Meta e in locale                  |

### Come funziona la creazione

Passi l'array `components` di Meta **così com'è**. Questo mantiene l'endpoint leggero e ti permette
di costruire *qualsiasi* modello supportato da Meta: testo, intestazioni media, pulsanti, OTP, ecc. Gli
unici campi obbligatori sono `connectionId`, `name` e `components`. `category` è uno tra
`MARKETING`, `UTILITY` o `AUTHENTICATION` (default `MARKETING`); `language` è una locale di Meta come
`en_US` o `fr` (default `en`).

### Riferimento dei componenti

Un modello è una lista ordinata di componenti. Ognuno ha un `type`:

| Tipo      | Forma                                                    | Descrizione                                                                          |
| --------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `HEADER`  | `format: TEXT \| IMAGE \| VIDEO \| DOCUMENT \| LOCATION` | Facoltativo. Uno per modello. Le intestazioni media richiedono un handle di esempio. |
| `BODY`    | `text` + `example`                                       | Obbligatorio (tranne AUTHENTICATION). Contiene le variabili `{{1}}`… o `{{name}}`.   |
| `FOOTER`  | `text`                                                   | Piè di pagina breve facoltativo. Nessuna variabile.                                  |
| `BUTTONS` | `QUICK_REPLY \| URL \| PHONE_NUMBER \| COPY_CODE \| OTP` | Facoltativo. Fino a 10 pulsanti (le regole variano in base al tipo).                 |

> [!NOTE]
> **Gli esempi sono obbligatori**
>
> Ogni componente con variabili (o un'intestazione media) deve includere un `example` perché Meta
> possa revisionarlo: `"example": { "body_text": [["Alice", "#1024"]] }` per il corpo,
> `"example": { "header_handle": ["<id>"] }` per un'intestazione media.

### Modello di utilità / marketing (intestazione + corpo + pulsanti)

```bash title="POST /api/v1/templates"
curl -X POST https://wa.genuka.com/api/v1/templates \
  -H "Authorization: Bearer pk_live_xxx" -H "Content-Type: application/json" \
  -d '{
    "connectionId": "con_1",
    "name": "order_shipped",
    "language": "en_US",
    "category": "UTILITY",
    "components": [
      { "type": "HEADER", "format": "IMAGE",
        "example": { "header_handle": ["4::aW1hZ2Uv..."] } },
      { "type": "BODY",
        "text": "Hi {{1}}, order {{2}} just shipped. Track it any time.",
        "example": { "body_text": [["Alice", "#1024"]] } },
      { "type": "FOOTER", "text": "Reply STOP to opt out" },
      { "type": "BUTTONS", "buttons": [
        { "type": "URL", "text": "Track order",
          "url": "https://example.com/track/{{1}}", "example": ["https://example.com/track/1024"] },
        { "type": "QUICK_REPLY", "text": "Need help" }
      ] }
    ]
  }'

{ "data": { "id": "tpl_123", "status": "pending", "providerId": "12534…" } }
```

L'`example.header_handle` dell'intestazione media è l'handle di caricamento ripristinabile restituito
dal caricamento media di Meta; al momento dell'*invio* fornisci l'immagine reale tramite URL o media
id (vedi [Messaggi → modello](#messaggi)).

### Parametri con nome

Preferisci `{{name}}` al posizionale `{{1}}`? Imposta `parameterFormat: "NAMED"` e dai a ogni
variabile un `parameter_name` nell'esempio.

```json title="POST /api/v1/templates (con nome)"
{
  "connectionId": "con_1",
  "name": "appointment_reminder",
  "language": "en_US",
  "category": "UTILITY",
  "parameterFormat": "NAMED",
  "components": [
    { "type": "BODY",
      "text": "Hi {{customer_name}}, your appointment is on {{date}}.",
      "example": { "body_text_named_params": [
        { "param_name": "customer_name", "example": "Alice" },
        { "param_name": "date", "example": "June 20" }
      ] } }
  ]
}
```

### Modello di autenticazione (OTP)

I modelli di autenticazione consegnano codici monouso. Il testo del corpo e del pulsante è **fissato
da WhatsApp**: non scrivi tu il testo. Scegli solo il tipo di pulsante e alcune opzioni. Non sono
ammessi intestazioni, media, URL né emoji.

| Tipo        | Forma                 | Descrizione                                                                              |
| ----------- | --------------------- | ---------------------------------------------------------------------------------------- |
| `COPY_CODE` | `otp_type: COPY_CODE` | Il cliente tocca per copiare il codice. Il più semplice, funziona ovunque.               |
| `ONE_TAP`   | `otp_type: ONE_TAP`   | Compilazione automatica su Android. Richiede `package_name` + `signature_hash`.          |
| `ZERO_TAP`  | `otp_type: ZERO_TAP`  | Codice consegnato in modo silenzioso all'app. Richiede lo stesso collegamento con l'app. |

```json title="POST /api/v1/templates (autenticazione)"
{
  "connectionId": "con_1",
  "name": "verification_code",
  "language": "en_US",
  "category": "AUTHENTICATION",
  "messageSendTtlSeconds": 600,
  "components": [
    { "type": "BODY", "add_security_recommendation": true },
    { "type": "FOOTER", "code_expiration_minutes": 10 },
    { "type": "BUTTONS", "buttons": [
      { "type": "OTP", "otp_type": "COPY_CODE", "text": "Copy code" }
    ] }
  ]
}
```

Per `ONE_TAP` / `ZERO_TAP`, aggiungi il collegamento con l'app al pulsante OTP:
`"autofill_text": "Autofill"`,
`"supported_apps": [{ "package_name": "com.example.app", "signature_hash": "K8a..." }]`.

> [!NOTE]
> **Inviare il codice**
>
> Creare il modello non invia mai nulla. Per consegnare un codice invii un messaggio `template` con
> la scorciatoia `otp`: vedi [Messaggi → modello di autenticazione](#messaggi).

### Aggiornare gli stati

L'esito di una revisione ti arriva come [webhook](https://wa.genuka.com/it/docs/webhooks): è su questa via che devi
costruire. Ma un webhook mai consegnato (un endpoint fuori servizio, un'integrazione aggiunta in un
secondo momento) lascia il modello in `pending` qui molto tempo dopo che Meta lo ha approvato, e una
campagna che si rifiuta di partire senza un motivo visibile. `POST /api/v1/templates/sync` rilegge la
verità da Meta e la riscrive.

```bash title="POST /api/v1/templates/sync"
curl -X POST https://wa.genuka.com/api/v1/templates/sync \
  -H "Authorization: Bearer pk_live_xxx" -H "Content-Type: application/json" \
  -d '{ "companyId": "cmp_1" }'
```

Il corpo è facoltativo: senza alcun campo, l'aggiornamento copre tutti gli account WhatsApp che la tua
chiave può raggiungere; `companyId` lo restringe a un cliente e `connectionId` alla WABA di un solo
numero. La risposta nomina ogni account WhatsApp che ha toccato (così un account irraggiungibile viene
segnalato invece di essere nascosto) e restituisce le righe appena scritte, il che ti risparmia un
`GET` successivo.

```json title="200 OK"
{
  "data": {
    "wabas": [{ "wabaId": "1029…", "companyId": "cmp_1", "ok": true }],
    "synced": 1,
    "failed": 0,
    "templates": [
      { "id": "tpl_1", "name": "order_shipped", "language": "fr", "status": "approved", "…": "…" }
    ]
  }
}
```

Un aggiornamento in cui *tutti* gli account hanno rifiutato risponde `502 meta_rejected` con gli
stessi `results` nel corpo; un fallimento parziale resta un `200` che sei tenuto a leggere.
`GET /api/v1/templates?sync=true` esegue lo stesso aggiornamento in linea prima di elencare, e accetta
gli stessi filtri `companyId` / `connectionId`.

> [!NOTE]
> **È una via di riparazione, non un ciclo di polling**
>
> Ogni chiamata consuma una lettura Meta per account WhatsApp. Eseguila in modo pianificato se vuoi
> (ogni ora è più che sufficiente), ma mantieni il webhook come il modo normale in cui arrivano gli
> stati.

## Campagne

| Metodo | Endpoint                            | Descrizione                                    |
| ------ | ----------------------------------- | ---------------------------------------------- |
| `GET`  | `/api/v1/campaigns`                 | Elenca le campagne (facoltativo `?companyId=`) |
| `POST` | `/api/v1/campaigns`                 | Crea una campagna con destinatari              |
| `GET`  | `/api/v1/campaigns/{id}`            | Una campagna con le statistiche di consegna    |
| `GET`  | `/api/v1/campaigns/{id}/recipients` | Stato per destinatario (`?status=`, `?limit=`) |
| `POST` | `/api/v1/campaigns/{id}/launch`     | Invia a tutti i destinatari in attesa          |

### Creare una campagna

Ogni destinatario ha le proprie `variables`. La forma semplice è un array posizionale per i parametri
del corpo `{{1}}, {{2}}…`. Per intestazioni media, pulsanti o codici OTP, passa invece un oggetto
completo (`{ "body": [...], "header": {...}, "buttons": [...] }`), con la stessa forma accettata da
[Messaggi → modello](#messaggi). Il modello deve essere `approved` prima del lancio. Qui sotto,
`tpl_124` è un modello con solo corpo; `tpl_123` (`order_shipped` sopra, con intestazione immagine e
pulsante URL) richiederebbe la forma completa per ogni destinatario.

```bash title="POST /api/v1/campaigns"
curl -X POST https://wa.genuka.com/api/v1/campaigns \
  -H "Authorization: Bearer pk_live_xxx" -H "Content-Type: application/json" \
  -d '{
    "connectionId": "con_1",
    "templateId": "tpl_124",
    "name": "June promo",
    "recipients": [
      { "to": "+237690000001", "variables": ["Alice", "#1024"] },
      { "to": "+237690000002", "variables": ["Bob", "#1025"] }
    ]
  }'

{ "data": { "id": "cmp_9", "name": "June promo", "status": "draft", "_count": { "recipients": 2 } } }
```

### Lancio

```bash title="POST /api/v1/campaigns/{id}/launch"
curl -X POST https://wa.genuka.com/api/v1/campaigns/cmp_9/launch \
  -H "Authorization: Bearer pk_live_xxx"

{ "data": { "sent": 2, "failed": 0, "skipped": 0 } }
```

> [!NOTE]
> **Limiti**
>
> Non facciamo mai pagare un messaggio: Meta fattura direttamente la tua WABA. I destinatari però
> contano sulla quota di messaggi del tuo piano per il periodo, e l'intera lista viene verificata
> prima del primo invio, quindi un lancio che non rientrerebbe viene rifiutato subito con
> `402 plan_limit_messages` invece di fermarsi a metà. Vengono consumati solo i destinatari che Meta
> ha effettivamente accettato. La V1 invia in modo sincrono: mantieni liste di dimensioni moderate;
> l'invio in coda per le liste grandi è nella roadmap.

## Media

Carica un file una volta, invialo tutte le volte che serve. L'archiviazione è **privata**: niente di
ciò che viene salvato qui è raggiungibile da un URL pubblico, e Meta non scarica mai il file; gli
consegniamo i byte da server a server al momento dell'invio.

```bash title="POST /api/v1/media (multipart)"
curl -X POST https://wa.genuka.com/api/v1/media \
  -H "Authorization: Bearer pk_live_xxx" \
  -F "companyId=cmp_1" \
  -F "file=@briefing.pdf"

{ "data": {
    "id": "ast_1",
    "url": "https://wa.genuka.com/api/v1/media/ast_1/content",
    "expiresAt": "2026-09-18T09:12:00.000Z",
    "mimeType": "application/pdf",
    "kind": "document",
    "sizeBytes": 481203,
    "filename": "briefing.pdf"
  },
  "deduplicated": false }
```

> [!NOTE]
> **Due limiti, dichiarati subito**
>
> **Conservazione: 30 giorni.** Ogni file viene eliminato definitivamente 30 giorni dopo il
> caricamento, e `expiresAt` indica esattamente quando. È la finestra di Meta stessa: oltre quel
> termine, la loro copia sparisce comunque. Un invio che fa riferimento a un file scaduto risponde
> `404 media_not_found`.
>
> **Archiviazione: in base al piano.** 1 GB su Starter, 3 GB su Growth, 5 GB su Scale, su misura su
> Enterprise, sommando tutti i clienti. Il limite riguarda ciò che è *conservato*: eliminare un file
> libera subito lo spazio. Un caricamento che lo supererebbe risponde `402 plan_limit_media` prima
> che venga salvato un solo byte. `GET /api/v1/media` restituisce il valore attuale in `storage`.

`url` è un endpoint di questa API, non un link di condivisione: richiede la tua chiave e rifiuta
qualsiasi chiamata fuori dal suo ambito. Byte identici già salvati per questo cliente vengono
restituiti così come sono con un `200` e `deduplicated: true`, invece di essere salvati due volte.

| Rotta                              | Descrizione                                                                                                                                                              |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `POST /api/v1/media`               | Caricamento. Multipart: `file` (obbligatorio), `companyId` (obbligatorio con una chiave partner a livello globale), `filename` (facoltativo).                            |
| `GET /api/v1/media`                | Elenco. Filtri `kind`, `companyId`, paginazione a cursore, più il valore `storage`.                                                                                      |
| `GET /api/v1/media/{id}`           | I metadati di un file.                                                                                                                                                   |
| `GET /api/v1/media/{id}/content`   | I byte, autenticati dalla tua chiave.                                                                                                                                    |
| `DELETE /api/v1/media/{id}`        | Elimina subito, senza attendere la scadenza.                                                                                                                             |
| `POST /api/v1/media/header-handle` | Genera l'`header_handle` per l'intestazione di un modello. Multipart: `file` (obbligatorio), `connectionId` **o** `companyId` (nessuno dei due, con una chiave cliente). |

### L'intestazione media di un modello: l'`header_handle`

Creare un modello la cui intestazione è IMAGE, VIDEO o DOCUMENT richiede un `example.header_handle`,
che Meta emette solo tramite la sua Resumable Upload API. **Non** è la stessa cosa di un `assetId`:
un handle viene consumato una sola volta, alla creazione del modello, e un invio lo rifiuta. Al
contrario, un `assetId` non serve a nulla al momento della creazione.

```bash title="POST /api/v1/media/header-handle (multipart)"
curl -X POST https://wa.genuka.com/api/v1/media/header-handle \
  -H "Authorization: Bearer pk_live_xxx" \
  -F "connectionId=con_1" \
  -F "file=@catalogue.pdf"

{ "data": {
    "handle": "4::YXBwbGljYXRpb24vcGRm…",
    "filename": "catalogue.pdf",
    "mimeType": "application/pdf",
    "sizeBytes": 481203
  } }
```

Indica il cliente come si aspetta ogni altra rotta `/media` (`-F "companyId=cmp_1"`) oppure un numero
specifico (`-F "connectionId=con_1"`); una chiave cliente non ha bisogno di nessuno dei due. L'handle
è lo stesso in entrambi i casi: la sessione di caricamento appartiene all'app Meta, non a un numero.

Riporta quell'`handle` nella definizione del modello:

```json title="POST /api/v1/templates"
{
  "connectionId": "con_1",
  "name": "morning_brief",
  "language": "en_US",
  "category": "UTILITY",
  "components": [
    { "type": "HEADER", "format": "DOCUMENT",
      "example": { "header_handle": ["4::YXBwbGljYXRpb24vcGRm…"] } },
    { "type": "BODY", "text": "Hi {{1}}, your brief for {{2}} is attached.",
      "example": { "body_text": [["Ana", "March 12"]] } }
  ]
}
```

Formati accettati: `image/jpeg`, `image/png`, `video/mp4`, `video/3gpp`, `application/pdf`.
Dimensione massima 4 MB; oltre, la risposta è `413 media_too_large`. Non conserviamo nulla dal nostro
lato: l'handle è monouso, quindi archiviarlo non servirebbe a niente.

### Inviare un file archiviato

Passa `assetId` ovunque sia previsto un oggetto media, comprese le intestazioni dei modelli.
Risolviamo il `media_id` di Meta per il numero di telefono giusto e lo rinnoviamo man mano che
invecchia.

```json title="POST /api/v1/messages"
{
  "connectionId": "con_1",
  "to": "+237600000000",
  "document": { "assetId": "ast_1", "filename": "briefing.pdf" }
}
```

`id` (un `media_id` di Meta che hai generato tu) e `link` (un URL pubblico che Meta scarica) sono
ancora accettati. `assetId` è quello da preferire: è l'unico che non espone il file su nessun URL, e
l'unico che non ti scade sotto il naso dopo 30 giorni.

## Messaggi

| Metodo | Endpoint           | Descrizione                                  |
| ------ | ------------------ | -------------------------------------------- |
| `POST` | `/api/v1/messages` | Invia un singolo messaggio di qualsiasi tipo |

Un solo endpoint invia tutti i tipi di messaggio WhatsApp. Passa sempre `connectionId` e `to`, poi
**esattamente un** campo di contenuto dalla tabella qui sotto. Aggiungi `replyTo` (il `wamid` di un
messaggio ricevuto) per citare o rispondere a un messaggio.

| Campo                                                | Finestra    | Descrizione                                                                                                                                                            |
| ---------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `template`                                           | a pagamento | Modello pre-approvato. L'unico modo per avviare una conversazione fuori dalla finestra di 24 h.                                                                        |
| `text`                                               | gratis\*    | `{ "text": "Hi" }` oppure `{ "text": { "body": "…", "previewUrl": true } }`                                                                                            |
| `image` / `video` / `audio` / `document` / `sticker` | gratis\*    | `{ "image": { "assetId": "ast_1" } }` (consigliato), `{ "link": "…" }` oppure `{ "id": "<media-id>" }`; `caption`/`filename` facoltativi                               |
| `location`                                           | gratis\*    | `{ "location": { "latitude": …, "longitude": …, "name": "…", "address": "…" } }`                                                                                       |
| `contacts`                                           | gratis\*    | `{ "contacts": [ … oggetti contatto di Meta … ] }`                                                                                                                     |
| `reaction`                                           | gratis\*    | `{ "reaction": { "messageId": "wamid…", "emoji": "👍" } }`                                                                                                             |
| `buttons` / `list` / `cta`                           | gratis\*    | Pulsanti di risposta interattivi, un menu a lista o un pulsante URL di call-to-action.                                                                                 |
| `locationRequest`                                    | gratis\*    | `{ "locationRequest": { "body": "Where should we deliver?" } }` — mostra un pulsante per inviare la posizione.                                                         |
| `callPermissionRequest`                              | gratis\*    | `{ "callPermissionRequest": { "body": "Can we call you back?" } }` — chiede al cliente il permesso di chiamarlo su WhatsApp (`body` facoltativo). Growth o superiore.  |
| `voiceCall`                                          | gratis\*    | `{ "voiceCall": { "body": "Call us on WhatsApp", "displayText": "Call", "ttlMinutes": 120 } }` — un pulsante che chiama questo numero su WhatsApp. Growth o superiore. |
| `raw`                                                | gratis\*    | Via di fuga per tutto il resto (Flows, indirizzo, catalogo): un frammento completo di tipo della Cloud API.                                                            |

> [!NOTE]
> **La finestra di 24 ore**
>
> Solo gli invii `template` possono avviare una conversazione. Tutto ciò che è segnato `free*` è un
> messaggio di *sessione* libero: viene consegnato solo se il cliente ha scritto all'azienda nelle
> ultime 24 ore. Fuori da quella finestra, usa un `template`. Tutti gli invii restituiscono
> `{ "data": { "messageId": "wamid…" } }`.

Un `200` significa che Meta ha *accettato* il messaggio, non che sia stato consegnato. Lo stato
finale (`sent` → `delivered` → `read`, oppure `failed`) arriva in modo asincrono sui tuoi
[webhook](https://wa.genuka.com/it/docs/webhooks). In `to`, includi sempre il `+` e il prefisso internazionale (per
esempio `+237690000001`): ometterlo può instradare male il messaggio. I media passati tramite `link`
vengono messi in cache da Meta per \~10 minuti, quindi riusa lo stesso URL per la stessa risorsa (o
aggiungi una query string univoca per invalidare la cache).

### Messaggio con modello

Il caso semplice è un modello le cui uniche variabili stanno nel corpo, come `order_update` qui sotto
(nessuna intestazione media, nessun pulsante dinamico). `variables` è un array posizionale; puoi anche
usare `bodyNamed` per i modelli con nome, `header` per un'intestazione media o di testo, e `buttons`
per i parametri dei pulsanti dinamici. Un invio deve compilare tutti i parametri dichiarati dal
modello: `order_shipped`, sopra, ha un'intestazione immagine e un pulsante URL dinamico, quindi
richiede la seconda forma; con le sole variabili del corpo, Meta lo rifiuta.

```bash title="POST /api/v1/messages (modello, semplice)"
curl -X POST https://wa.genuka.com/api/v1/messages \
  -H "Authorization: Bearer pk_live_xxx" -H "Content-Type: application/json" \
  -d '{
    "connectionId": "con_1",
    "to": "+237690000001",
    "template": { "name": "order_update", "language": "en_US", "variables": ["Alice", "#1024"] }
  }'

{ "data": { "messageId": "wamid.HBg…" } }
```

```json title="POST /api/v1/messages (modello, intestazione + corpo + pulsante)"
{
  "connectionId": "con_1",
  "to": "+237690000001",
  "template": {
    "name": "order_shipped",
    "language": "en_US",
    "header": { "image": { "link": "https://example.com/orders/1024.png" } },
    "variables": ["Alice", "#1024"],
    "buttons": [
      { "type": "url", "text": "1024" }
    ]
  }
}
```

Il `buttons[].text` compila la parte dinamica di un pulsante URL (il `{{1}}` in
`https://example.com/track/{{1}}`). Per una risposta rapida usa
`{ "type": "quick_reply", "payload": "…" }`; per un codice coupon usa
`{ "type": "copy_code", "code": "SAVE20" }`. Parametri del corpo con nome:
`"bodyNamed": { "customer_name": "Alice" }`.

### Modello di autenticazione

Passa il codice una sola volta con la scorciatoia `otp`: compiliamo noi sia il corpo sia il pulsante
OTP (il formato richiesto da Meta).

```json title="POST /api/v1/messages (autenticazione)"
{
  "connectionId": "con_1",
  "to": "+237690000001",
  "template": { "name": "verification_code", "language": "en_US", "otp": "472913" }
}
```

### Messaggi di sessione liberi

```json title="testo"
{ "connectionId": "con_1", "to": "+237690000001", "text": "Thanks, talk soon!" }
```

```json title="immagine (con didascalia)"
{ "connectionId": "con_1", "to": "+237690000001",
  "image": { "link": "https://example.com/promo.jpg", "caption": "New arrivals 🎉" } }
```

```json title="documento"
{ "connectionId": "con_1", "to": "+237690000001",
  "document": { "link": "https://example.com/invoice.pdf", "filename": "invoice-1024.pdf" } }
```

```json title="pulsanti di risposta interattivi"
{
  "connectionId": "con_1",
  "to": "+237690000001",
  "buttons": {
    "body": "Confirm your order?",
    "footer": "Acme Coffee",
    "buttons": [
      { "id": "yes", "title": "Confirm" },
      { "id": "no",  "title": "Cancel" }
    ]
  }
}
```

```json title="lista interattiva"
{
  "connectionId": "con_1",
  "to": "+237690000001",
  "list": {
    "body": "Pick a delivery slot",
    "button": "Choose",
    "sections": [
      { "title": "Today", "rows": [
        { "id": "t1", "title": "12:00–14:00" },
        { "id": "t2", "title": "14:00–16:00", "description": "Most popular" }
      ] }
    ]
  }
}
```

```json title="pulsante URL di call-to-action"
{
  "connectionId": "con_1",
  "to": "+237690000001",
  "cta": { "body": "Your receipt is ready.", "displayText": "View receipt", "url": "https://example.com/r/1024" }
}
```

```json title="risposta nel thread + reazione"
{ "connectionId": "con_1", "to": "+237690000001", "replyTo": "wamid.HBg…", "text": "On its way!" }

{ "connectionId": "con_1", "to": "+237690000001",
  "reaction": { "messageId": "wamid.HBg…", "emoji": "👍" } }
```

## Chiamate WhatsApp

Piano Growth o superiore. Il tuo stack (un agente vocale, un softphone WebRTC) effettua e risponde
alle chiamate; Genuka WA inoltra la segnalazione a Meta e ti restituisce i webhook `call.*`. L'audio
non passa mai da noi: l'SDP descrive un percorso tra Meta e il tuo stack. Vedi la guida
[Collegare un agente vocale](https://wa.genuka.com/it/docs/guides/voice-agent) per i flussi dall'inizio alla fine.

| Metodo  | Endpoint                                          | Descrizione                                                                                                                     |
| ------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `GET`   | `/api/v1/numbers/{id}/calling`                    | Impostazioni delle chiamate di un numero: `status`, `callIconVisibility`, `callHours`, `callbackPermissionStatus`, `sipEnabled` |
| `PATCH` | `/api/v1/numbers/{id}/calling`                    | Le modifica. Un vero patch: il resto viene mantenuto.                                                                           |
| `POST`  | `/api/v1/calls`                                   | Un'azione di chiamata, inoltrata a Meta: `connect`, `pre_accept`, `accept`, `reject`, `terminate`                               |
| `GET`   | `/api/v1/calls/permissions?waId=…&connectionId=…` | Se puoi chiamare questo utente adesso (`canCall`) e se puoi chiederglielo (`canRequestPermission`)                              |

```json title="PATCH /api/v1/numbers/con_1/calling — attivare le chiamate, in orario d'ufficio"
{
  "status": "ENABLED",
  "callHours": {
    "status": "ENABLED",
    "timezoneId": "Africa/Douala",
    "weeklyOperatingHours": [{ "dayOfWeek": "MONDAY", "openTime": "0800", "closeTime": "1800" }],
    "holidaySchedule": []
  }
}
```

```json title="POST /api/v1/calls — rispondere a una chiamata in arrivo"
{ "action": "accept", "callId": "wacid.HBgL…", "sdp": "v=0\r\no=- 8236… (la tua risposta SDP)" }
```

```json title="POST /api/v1/calls — chiamare un cliente che ha dato il permesso"
{ "connectionId": "con_1", "action": "connect", "to": "+237690000001", "sdp": "v=0\r\n… (la tua offerta SDP)" }
```

* `sdp` è solo l'SDP: il suo tipo deriva dall'azione (offerta su `connect`, risposta su
  `pre_accept` / `accept`). `connect` restituisce `{ "data": { "action": "connect", "callId": "wacid…" } }`.
* `connectionId` può essere omesso quando `callId` indica una chiamata che Genuka WA ha già visto (il
  webhook di una chiamata in arrivo, o un `connect` effettuato qui).
* Una chiamata in arrivo squilla per circa 30 secondi: `pre_accept` deve partire entro quella
  finestra.

| Stato | `error`                                            | Quando                                                                                                    |
| ----- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `403` | `plan_feature_unavailable`                         | Il piano non include le chiamate (Starter).                                                               |
| `409` | `calling_unavailable_coexistence`                  | Il numero è condiviso con l'app WhatsApp Business: WhatsApp non consente chiamate tramite API su di esso. |
| `409` | `calling_sip_configured`                           | Il numero segnala le chiamate via SIP, configurato fuori da Genuka WA (solo `PATCH`).                     |
| `409` | `number_offboarded`                                | Il numero ha lasciato la piattaforma: ricollegalo.                                                        |
| `404` | `call_not_found`                                   | `callId` senza `connectionId`, e nessuna chiamata nota con quell'id: passa il `connectionId`.             |
| `400` | `invalid_call_action` / `invalid_calling_settings` | Tutti i problemi del corpo, in una volta sola, in `issues`.                                               |
| `422` | `meta_error`                                       | Meta ha rifiutato: numero non idoneo, nessun permesso di chiamata, paese escluso… con le parole di Meta.  |

Webhook: `call.connect` (con `data.session.sdp`), `call.status_changed`, `call.terminated` e
`call.permission_replied` (vedi [Webhook](https://wa.genuka.com/it/docs/webhooks)).

## Abbonamento

| Metodo | Endpoint               | Descrizione                      |
| ------ | ---------------------- | -------------------------------- |
| `GET`  | `/api/v1/subscription` | Piano attuale, limiti e utilizzo |

```json title="GET /api/v1/subscription"
{
  "plan": { "code": "growth", "name": "Growth" },
  "interval": "monthly",
  "currency": "XAF",
  "status": "active",
  "currentPeriodEnd": "2026-07-18T00:00:00.000Z",
  "billedNumbers": 9,
  "usage": { "numbers": 9, "messages": 12480, "seats": 3 },
  "limits": { "maxNumbers": 9, "monthlyMessages": 45000, "maxSeats": 5 }
}
```

## Errori

```text title="Esempi"
401 { "error": "missing_bearer_token" }      // nessun header Authorization
401 { "error": "invalid_token" }             // chiave sconosciuta / revocata, o account inattivo
403 { "error": "account_deactivated", "message": "Deactivated Account" }
                                             // quell'azienda è sospesa: la sua chiave smette
                                             // di funzionare, e ogni richiesta che la nomina
                                             // viene rifiutata, anche con una chiave di account
400 { "error": "missing_fields", "message": "…" }
400 { "error": "missing_content", "message": "…" }  // nessun campo di contenuto in un invio
400 { "error": "invalid_media", "message": "…" }    // media senza assetId, id né link
402 { "error": "plan_limit_media", "message": "…" } // raggiunto il limite di archiviazione del piano
404 { "error": "media_not_found", "message": "…" }  // assetId sconosciuto, o oltre i 30 giorni
402 { "error": "plan_limit_numbers" }        // tutti i numeri pagati dal piano sono in uso
402 { "error": "plan_limit_messages" }       // la quota di messaggi del periodo è esaurita
402 { "error": "subscription_past_due" }     // prova o periodo pagato scaduto senza rinnovo
404 { "error": "connection_not_found" }
404 { "error": "template_not_found" }
409 { "error": "template_exists" }
413 { "error": "media_too_large", "message": "…" } // intestazione del modello oltre 4 MB
422 { "error": "meta_rejected", "message": "…", "meta": { … } }
                                             // Meta ha letto il payload e l'ha rifiutato
502 { "error": "meta_rejected", "message": "…" }   // Graph irraggiungibile o in errore
```

### Ciò che Meta ha rifiutato restituisce 422, non 502

Quando Graph legge un payload e lo rifiuta (un modello malformato, una variabile senza esempio, un
numero non predisposto), la risposta è un **422**, e il suo corpo contiene un oggetto `meta` con il
codice di errore di Meta, il suo `traceId` e la sua classe:

```json title="422 — rifiutato da Meta"
{
  "error": "meta_rejected",
  "message": "Invalid parameter",
  "meta": {
    "errorClass": "template",
    "retryable": false,
    "code": 100,
    "details": "body_text example count does not match the number of variables",
    "traceId": "AbC…"
  }
}
```

`traceId` è ciò che chiede il supporto di Meta: citalo testualmente.

Un **502** è riservato a ciò che la parola descrive: Graph irraggiungibile, o Graph stesso in errore.
Restituire un payload rifiutato come 502 lo rendeva impossibile da diagnosticare: la nostra CDN
risponde ai 5xx dell'origine con la propria pagina di errore, sostituendo quel corpo JSON con
l'unica riga `error code: 502`. Il motivo del rifiuto non ti arrivava mai. I corpi 4xx passano senza
modifiche.

## Log delle richieste

Ogni risposta contiene un header `x-request-id`. Lo stesso id identifica la chiamata nella tua
dashboard, in Log, dove ogni richiesta è conservata con il suo stato, la sua durata, il suo corpo e,
quando è fallita, la risposta che abbiamo restituito. Le consegne dei webhook sono elencate accanto,
con il loro payload firmato esatto e un pulsante per reinviarle.

Quanto indietro arriva il log dipende dal tuo piano: 7 giorni su Starter, 30 su Growth, 90 su Scale.

> [!NOTE]
> **Campi oscurati**
>
> I corpi vengono conservati per rendere riproducibile un errore, tranne tutto ciò che somiglia a una
> credenziale: i valori `password`, `token`, `secret` e `api_key` vengono sostituiti prima che la
> riga venga scritta.
