# Collegare un agente vocale alle chiamate WhatsApp

URL: https://wa.genuka.com/it/docs/guides/voice-agent
Language: Italian

> Ricevi ed effettua chiamate WhatsApp con il tuo agente vocale o il tuo stack WebRTC: attivare le chiamate, webhook call.*, azioni di chiamata con SDP, permessi.

Genuka WA inoltra le chiamate WhatsApp al tuo stack: un agente vocale, un softphone WebRTC, un
contact center. Attivi le chiamate per il numero, ricevi ogni chiamata via webhook con il suo SDP e
rispondi tramite l'API. L'audio passa direttamente tra Meta e il tuo stack; non transita mai da
Genuka WA. Le chiamate sono incluse a partire dal piano Growth.

## Prima di iniziare

* **Il numero deve essere idoneo.** Meta riserva le chiamate ai numeri con un volume di
  conversazioni sufficiente, ed esclude alcuni paesi (tra cui Stati Uniti, Canada e Nigeria).
  Quando non si applica, Meta rifiuta con il proprio messaggio, inoltrato così com'è (`422`).
* **Non in coesistenza.** Un numero condiviso con l'app WhatsApp Business non ha chiamate via API
  (`409 calling_unavailable_coexistence`).
* **Un webhook iscritto alle chiamate.** Iscrivi un endpoint a `call.connect`,
  `call.status_changed`, `call.terminated` e `call.permission_replied` (vedi
  [Webhook](https://wa.genuka.com/it/docs/webhooks)).

## 1. Attiva le chiamate per il numero

```bash
curl -X PATCH https://wa.genuka.com/api/v1/numbers/con_1/calling \
  -H "Authorization: Bearer pk_live_…" -H "Content-Type: application/json" \
  -d '{ "status": "ENABLED" }'
```

La pagina del numero nella dashboard ha lo stesso interruttore. `callHours` limita le chiamate in
arrivo ai tuoi orari di apertura; `callbackPermissionStatus` fa sì che un cliente che ti chiama ti
autorizzi a richiamarlo.

## 2. Un cliente ti chiama

1. Arriva il webhook `call.connect` con `data.callId`, `data.from` (il cliente) e
   `data.session.sdp`, l'offerta SDP del cliente.
2. Il tuo stack costruisce la sua risposta SDP e la invia subito come `pre_accept`: l'audio può
   stabilirsi mentre l'agente risponde.
3. Quando l'agente è pronto, `accept` con la stessa risposta SDP.
4. `terminate` per riagganciare. `call.terminated` arriva in ogni caso, con la durata.

```json title="POST /api/v1/calls"
{ "action": "pre_accept", "callId": "wacid.HBgL…", "sdp": "v=0\r\n… (la tua risposta SDP)" }
```

La chiamata squilla per circa **30 secondi**. L'intero percorso, dal webhook al tuo `pre_accept`,
deve starci dentro: conferma subito la ricezione del webhook e gestisci la chiamata in parallelo.
Basta `callId`, senza `connectionId`: Genuka WA sa a quale numero appartiene la chiamata (altrimenti
`404 call_not_found`: passa il `connectionId`).

> [!NOTE]
> **Le iscrizioni si basano sul campo di Meta**
>
> I webhook sono filtrati per campo di Meta: iscriversi a `call.permission_replied` porta anche gli
> eventi `message.*`, perché la risposta è un messaggio. Filtra sul `type` della busta. Il
> `bizOpaqueCallbackData` di un'azione di chiamata torna come `data.callbackData`.

## 3. Chiami un cliente

Meta richiede il permesso del cliente prima di qualsiasi chiamata in uscita.

1. Verificalo: `GET /api/v1/calls/permissions?waId=+237690000001&connectionId=con_1`. Se `canCall`
   è true, vai al passaggio 3.
2. Altrimenti, e se `canRequestPermission` è true, chiedilo (dentro la finestra di 24 ore):

   ```json title="POST /api/v1/messages"
   { "connectionId": "con_1", "to": "+237690000001",
     "callPermissionRequest": { "body": "We would like to call you back about your order." } }
   ```

   La risposta del cliente arriva come `call.permission_replied`. Meta limita quante volte puoi
   chiedere per cliente e al giorno: `canRequestPermission` false significa aspettare, non
   chiedere di nuovo.
3. Avvia la chiamata con la tua offerta SDP. La risposta SDP del cliente arriva su `call.connect`.

   ```json title="POST /api/v1/calls"
   { "connectionId": "con_1", "action": "connect", "to": "+237690000001", "sdp": "v=0\r\n… (la tua offerta SDP)" }
   ```

## Lascia che il cliente ti chiami

Un pulsante di chiamata WhatsApp, in una conversazione aperta, permette al cliente di chiamarti con
un tocco:

```json title="POST /api/v1/messages"
{ "connectionId": "con_1", "to": "+237690000001",
  "voiceCall": { "body": "Any question? Call us on WhatsApp.", "displayText": "Call" } }
```

Fuori dalla finestra di 24 ore, usa un modello con un pulsante `VOICE_CALL`.

## Errori da conoscere

| Stato | `error`                           | Cosa fare                                                                      |
| ----- | --------------------------------- | ------------------------------------------------------------------------------ |
| `403` | `plan_feature_unavailable`        | Passa al piano Growth.                                                         |
| `409` | `calling_unavailable_coexistence` | Usa un numero non condiviso con l'app WhatsApp Business.                       |
| `400` | `invalid_call_action`             | Correggi il corpo: l'elenco completo è in `issues`.                            |
| `422` | `meta_error`                      | Leggi il messaggio di Meta: numero non idoneo, nessun permesso, paese escluso… |

Il riferimento completo è in [API · Chiamate WhatsApp](https://wa.genuka.com/it/docs/api#chiamate-whatsapp), e l'SDK
TypeScript in [Calling](https://wa.genuka.com/sdk/calling).
