API: configurare il trasferimento di chiamata

Il trasferimento di chiamata di un agente vocale AI si configura via API con una richiesta di attivazione, POST /agents/ID/sip-calling/enable, che imposta in un colpo solo il numero da cui partono i trasferimenti, il tempo di squillo, la rubrica delle destinazioni e i due messaggi che guidano l'agente: la presentazione quando qualcuno risponde e il messaggio di mancata risposta quando nessuno risponde. Dopo l'attivazione, rubrica e messaggi si ritoccano con operazioni puntuali senza reinviare tutto.

Questa guida spiega ogni campo con il suo comportamento reale, gli esempi completi con curl e i codici di errore con cosa fare. Per capire che cosa fa il trasferimento assistito dal punto di vista di chi chiama e di chi risponde, e per scrivere una buona presentazione, leggi prima Trasferimento assistito: l'agente AI passa la chiamata. Le convenzioni comuni (chiave, header X-API-Key, formato degli errori) sono nella guida ai primi passi. Tutti i percorsi vanno aggiunti all'indirizzo base https://api.aptiva.cloud/external/api.

Cosa ti serve prima di iniziare#

Per attivare il trasferimento di chiamata via API servono tre cose:

1. L'ID dell'agente (agentId): nel pannello è accanto al nome dell'agente, nella forma #42.
2. L'ID del numero in uscita (companyPhoneNumberId): nel pannello, nella tabella dei numeri, colonna ID. Serve l'ID della riga del numero in uscita, attivo. Con il centralino collegato ad Aptiva è il numero dedicato al collegamento; con un numero Aptiva è il tuo numero Aptiva in uscita.
3. Se vuoi trasferire agli interni del centralino, il collegamento del centralino ad Aptiva deve essere già attivo: si richiede a noi, come spiegato nella guida Collegare il centralino all'agente vocale AI. Senza collegamento puoi comunque trasferire verso numeri pubblici, fissi o mobili.

Il trasferimento di chiamata si configura solo via API (o lo configuriamo noi su richiesta): il pannello non ha una schermata dedicata.

Attivare e riconfigurare il trasferimento#

L'attivazione è una richiesta POST /agents/ID/sip-calling/enable con un body JSON. La stessa richiesta è anche il modo per riconfigurare: non è un semplice interruttore ma un aggiornamento (upsert) della configurazione.

curl -sS -X POST "https://api.aptiva.cloud/external/api/agents/42/sip-calling/enable" \
  -H "X-API-Key: $APTIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companyPhoneNumberId": 123,
    "allowMultipleRequests": true,
    "ringTimeout": 20,
    "bridgeIntroductionMessage": "Presenta la chiamata a {contact_name} in due frasi: chi chiama e il motivo della chiamata, usando solo le informazioni emerse nella conversazione. Se il chiamante ha segnalato qualcosa di urgente, dillo per primo. Chiudi con «vi lascio in linea».",
    "bridgeNoAnswerMessage": "{contact_name} non ha risposto (motivo: {reason}). Scusati brevemente con il chiamante, spiega che al momento nessuno è disponibile e proponi due alternative: lasciare un messaggio che verrà consegnato, oppure essere richiamato indicando una fascia oraria. Prendi nota di nome, numero e motivo prima di salutare.",
    "addressBook": {
      "centralino": ["200"],
      "amministrazione": ["201", "202"],
      "ufficio tecnico": ["215"]
    }
  }'

I campi del body:

La risposta è 200 con lo stato completo della configurazione, lo stesso oggetto restituito da tutte le operazioni di questa guida:

{
  "enabled": true,
  "companyPhoneNumberId": 123,
  "allowMultipleRequests": true,
  "ringTimeout": 20,
  "bridgeIntroductionMessage": "Presenta la chiamata a {contact_name} in due frasi: ...",
  "bridgeNoAnswerMessage": "{contact_name} non ha risposto (motivo: {reason}). ...",
  "addressBook": {
    "centralino": ["200"],
    "amministrazione": ["201", "202"],
    "ufficio tecnico": ["215"]
  }
}

Cosa resta e cosa si sostituisce quando riconfiguri#

Quando richiami enable su un agente che ha già il trasferimento attivo, valgono queste regole:

• companyPhoneNumberId, allowMultipleRequests e ringTimeout vanno sempre reinviati: sono obbligatori a ogni chiamata e sostituiscono i valori precedenti.
• addressBook omesso → la rubrica esistente resta. Se lo invii, sostituisce l'intera rubrica: le voci non incluse scompaiono. Per aggiungere o togliere una singola voce usa le operazioni puntuali descritte più avanti.
• Messaggi omessi o null → restano quelli salvati. Con enable puoi impostare o cambiare un messaggio, ma non cancellarlo: per rimuoverlo esistono le DELETE dedicate.
• Alla prima attivazione la rubrica è obbligatoria: senza addressBook la risposta è 422 con codice SIP_CALLING_ADDRESS_BOOK_REQUIRED.

La rubrica: nomi, interni e numeri#

La rubrica (addressBook) è un oggetto JSON in cui ogni chiave è il nome di una destinazione e il valore è la lista dei suoi numeri. È ciò su cui ragiona l'agente: quando il chiamante dice «vorrei parlare con chi si occupa delle fatture», l'agente sceglie la voce con il nome più adatto e fa squillare i suoi numeri. Se una voce ha più numeri, squillano insieme e la chiamata va al primo che risponde.

I nomi delle voci#

I nomi delle voci devono essere parlanti: «amministrazione», «ufficio tecnico», «dott. rossi», non codici come «int201». L'agente li legge per capire dove trasferire, e usa il nome scelto nella presentazione tramite il segnaposto {contact_name}.

Due regole di normalizzazione da conoscere:

• I nomi vengono ripuliti dagli spazi ai bordi e convertiti in minuscolo. Se invii «Amministrazione», in risposta troverai «amministrazione», e con quel nome dovrai riferirti alla voce nelle operazioni puntuali.
• Due nomi che coincidono dopo la normalizzazione («Commerciale» e «commerciale») sono un errore di validazione.

I numeri: interni e numeri pubblici#

Ogni numero della rubrica può essere di due tipi, riconosciuti automaticamente:

Il limite di 5 cifre per gli interni non è arbitrario: nessuna sequenza di 1–5 cifre è un numero telefonico italiano valido, quindi un interno non può mai essere confuso con un numero pubblico. Con 6 cifre, invece, decine di migliaia di numeri fissi reali diventerebbero ambigui.

Gli interni funzionano solo se il centralino è collegato ad Aptiva: se la rubrica contiene almeno un interno e l'agente non lavora su un collegamento al centralino, la richiesta risponde 422 con codice SIP_CALLING_EXTENSION_WITHOUT_PBX_LINK. Il controllo vale a ogni salvataggio della configurazione dell'agente via API, non solo quando tocchi la rubrica: finché la configurazione resta incoerente, anche le altre modifiche via API a quell'agente ricevono lo stesso errore. La soluzione è togliere gli interni oppure richiedere il collegamento del centralino.

Altre regole sui numeri: i duplicati dentro la stessa voce vengono eliminati in silenzio; un numero né valido come pubblico né come interno risponde 422 con SIP_CALLING_PHONE_NUMBER_INVALID (nelle operazioni puntuali) o validation_error (in enable); un numero valido ma non italiano, oppure a sovrapprezzo, risponde 422 con SIP_CALLING_PHONE_NUMBER_NOT_ALLOWED.

I limiti#

La rubrica può contenere al massimo 200 voci e ogni voce al massimo 50 numeri. Deve esserci sempre almeno una voce, e ogni voce deve avere almeno un numero.

Le operazioni puntuali sulla rubrica#

Dopo l'attivazione, la rubrica si modifica senza reinviare tutto con quattro operazioni POST, tutte con risposta 200 e lo stato completo. Nei body il nome della voce (entryName) va indicato come lo vedi nella risposta, cioè in minuscolo, anche se in ingresso viene comunque normalizzato.

Aggiungere una voce con i suoi numeri:

curl -sS -X POST "https://api.aptiva.cloud/external/api/agents/42/sip-calling/address-book/entries" \
  -H "X-API-Key: $APTIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entryName": "commerciale", "numbers": ["230", "231"]}'

Se la voce esiste già: 409 con SIP_CALLING_ENTRY_ALREADY_EXISTS. Con la lista numbers vuota: 422 con validation_error.

Rimuovere una voce:

curl -sS -X POST "https://api.aptiva.cloud/external/api/agents/42/sip-calling/address-book/entries/remove" \
  -H "X-API-Key: $APTIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entryName": "commerciale"}'

Se la voce non esiste la risposta è comunque 200 senza modifiche. Se è l'ultima voce rimasta: 409 con SIP_CALLING_LAST_ENTRY_REMOVAL_FORBIDDEN, perché la rubrica non può restare vuota (per spegnere tutto usa la disattivazione).

Aggiungere un numero a una voce esistente:

curl -sS -X POST "https://api.aptiva.cloud/external/api/agents/42/sip-calling/address-book/entries/numbers" \
  -H "X-API-Key: $APTIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entryName": "commerciale", "number": "232"}'

Se la voce non esiste: 409 con SIP_CALLING_ENTRY_NOT_FOUND (crea prima la voce). Se il numero è già presente: 200 senza modifiche. Numero non valido: 422 con SIP_CALLING_PHONE_NUMBER_INVALID.

Rimuovere un numero da una voce:

curl -sS -X POST "https://api.aptiva.cloud/external/api/agents/42/sip-calling/address-book/entries/numbers/remove" \
  -H "X-API-Key: $APTIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entryName": "commerciale", "number": "232"}'

Voce o numero inesistenti: 200 senza modifiche. Se era l'ultimo numero della voce, la voce viene rimossa; se era l'ultimo numero dell'ultima voce: 409 con SIP_CALLING_LAST_ENTRY_REMOVAL_FORBIDDEN.

Tutte le operazioni puntuali (rubrica e messaggi) richiedono che il trasferimento sia già attivo: altrimenti rispondono 409 con SIP_CALLING_NOT_CONFIGURED.

I messaggi: presentazione e mancata risposta#

I due messaggi del trasferimento sono istruzioni per l'agente AI, non testi letti parola per parola. L'agente li riceve come indicazioni e formula da sé la frase da pronunciare, con le informazioni di quella specifica chiamata: il nome di chi chiama, il motivo, ciò che è emerso nella conversazione. Scrivili come scriveresti un'indicazione a un collega («presenta chi chiama e il motivo in due frasi»), non come un copione. Su come scrivere una buona presentazione, con esempi per settore, vedi la guida sul trasferimento assistito.

I segnaposto vengono sostituiti testualmente prima di passare l'istruzione all'agente: {contact_name} con il nome della destinazione scelta, {reason} con il motivo della mancata risposta. I valori di {reason} sono timeout (nessuno ha risposto in tempo), busy (occupato), rejected (rifiutata), unavailable (non raggiungibile), system_failure (errore tecnico) e, quando sono stati tentati più numeri, no_target_answered. Nel messaggio di presentazione {reason} non ha senso e non viene sostituito; altri testi fra graffe restano come sono.

Imposta sempre il messaggio di mancata risposta. Se manca, quando nessuno risponde l'agente non viene informato dell'esito: resta in attesa di una notifica che non arriva, e il chiamante resta senza risposta. Con il messaggio, invece, l'agente riprende la conversazione e sa che deve scusarsi, prendere un messaggio o proporre un richiamo.

I messaggi si impostano anche singolarmente con PUT e si rimuovono con DELETE:

# Imposta o sostituisce il messaggio di mancata risposta
curl -sS -X PUT "https://api.aptiva.cloud/external/api/agents/42/sip-calling/bridge-no-answer-message" \
  -H "X-API-Key: $APTIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bridgeNoAnswerMessage": "{contact_name} non è raggiungibile ({reason}). Scusati, proponi di lasciare un messaggio e prendi nota di nome, numero e motivo."}'

# Imposta o sostituisce il messaggio di presentazione
curl -sS -X PUT "https://api.aptiva.cloud/external/api/agents/42/sip-calling/bridge-introduction-message" \
  -H "X-API-Key: $APTIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bridgeIntroductionMessage": "Presenta la chiamata a {contact_name}: chi chiama e perché, in due frasi. Chiudi con «vi lascio in linea»."}'

# Rimuove il messaggio di presentazione (il collegamento avviene senza annuncio)
curl -sS -X DELETE "https://api.aptiva.cloud/external/api/agents/42/sip-calling/bridge-introduction-message" \
  -H "X-API-Key: $APTIVA_API_KEY"

Il body delle PUT deve contenere una stringa non vuota; non c'è un limite di lunghezza, ma un'istruzione di due o tre frasi funziona meglio di una pagina.

Il tempo di squillo (ringTimeout)#

ringTimeout è il tempo, in secondi, per cui l'agente fa squillare la destinazione prima di considerare la chiamata senza risposta. Via API è obbligatorio e deve valere almeno 1; un valore fra 20 e 30 secondi va bene per la maggior parte degli uffici.

Il criterio per sceglierlo è uno: deve essere inferiore al tempo dopo cui scatta la segreteria dell'interno o del cellulare che fai squillare. Una segreteria che risponde è, per il sistema telefonico, una risposta: l'agente presenterebbe la chiamata alla segreteria e lascerebbe il chiamante in linea con essa. Se i cellulari dei tuoi collaboratori hanno la segreteria a 25 secondi, imposta ringTimeout a 20.

Più tentativi nella stessa chiamata (allowMultipleRequests)#

allowMultipleRequests stabilisce se l'agente può chiedere più di un trasferimento nella stessa chiamata. Con true, se il primo tentativo fallisce (nessuno risponde all'amministrazione), l'agente può proporre e tentare un'altra destinazione (il centralino). Con false, dopo il primo trasferimento richiesto ogni ulteriore tentativo in quella chiamata viene rifiutato.

In ogni caso è in corso un solo trasferimento alla volta: true permette di riprovare in sequenza, non di far squillare due destinazioni diverse contemporaneamente (per quello si mettono più numeri nella stessa voce di rubrica). Per la maggior parte degli usi true è la scelta giusta.

Leggere lo stato e disattivare#

Lo stato della configurazione si legge con GET /agents/ID/sip-calling:

curl -sS "https://api.aptiva.cloud/external/api/agents/42/sip-calling" \
  -H "X-API-Key: $APTIVA_API_KEY"

La risposta è lo stesso oggetto restituito da enable. Quando il trasferimento non è attivo, enabled è false, gli altri campi sono null e addressBook è un oggetto vuoto.

La disattivazione è DELETE /agents/ID/sip-calling:

curl -sS -X DELETE "https://api.aptiva.cloud/external/api/agents/42/sip-calling" \
  -H "X-API-Key: $APTIVA_API_KEY"

Cancella l'intera configurazione, rubrica e messaggi inclusi: alla riattivazione dovrai reinviare tutto, addressBook compreso. Se vuoi solo sospendere il trasferimento per un periodo, salva prima lo stato con la GET e, alla riattivazione, reinvialo a enable togliendo il campo enabled, che la richiesta non prevede (risponderebbe 422 con validation_error). Controlla anche che companyPhoneNumberId non sia null: lo diventa se nel frattempo il numero non esiste più.

Codici di errore e cosa fare#

Tutti gli errori seguono il formato comune detail e code descritto nella guida ai primi passi. Qui i codici specifici del trasferimento:

Prossimi passi#

1. Attiva il trasferimento sul tuo agente con l'esempio di questa guida, poi fai una chiamata di prova e ascolta come l'agente presenta la chiamata: ritocca l'istruzione con una PUT finché suona bene. Gli esempi di presentazione per settore sono nella guida Trasferimento assistito: l'agente AI passa la chiamata.
2. Se vuoi trasferire agli interni del tuo centralino e non è ancora collegato, richiedi il collegamento dalla pagina Contatti seguendo la guida Collegare il centralino all'agente vocale AI: nessun costo di attivazione. I costi della conversazione dopo il trasferimento sono nella pagina Prezzi.
3. Per far partire le chiamate dai tuoi sistemi, continua con API: creare lead e avviare chiamate. Se preferisci che la rubrica e i messaggi li configuriamo noi, scrivici l'elenco delle voci: lo facciamo su richiesta.