Le chiamate di richiamata sono chiamate richieste da un utente finale. Con l'API di richiamata, puoi pianificare in modo programmatico le chiamate di richiamata e annullare quelle pianificate. Con queste funzionalità, puoi creare applicazioni che consentono agli utenti finali di richiedere chiamate di richiamata da una coda specificata. Gli utenti finali possono anche annullare le chiamate che hanno programmato in precedenza. Per informazioni sull'autenticazione con l'API di chiamata di callback, consulta Autenticazione di base.
Utilizza l'API di chiamata di richiamata
Puoi utilizzare l'API per le chiamate di richiamata per programmare le chiamate di richiamata e annullare le chiamate programmate.
Prenota una chiamata
Per pianificare una chiamata, chiama POST https://<subdomain>.<domain>/apps/api/v1/calls
e includi un corpo della richiesta simile al seguente:
{
"call_type": "ScheduledCall",
"menu_id": 12345,
"end_user_number": "+18005550100",
"scheduled_at": "2025-09-02T14:30:00Z"
}
Una richiesta riuscita restituisce un oggetto chiamata, incluso l'ID chiamata.
Annullare una chiamata programmata
Per annullare una chiamata programmata, chiama il numero PATCH
https://<subdomain>.<domain>/apps/api/v1/calls/scheduled/{id}/cancel. Specifica l'ID della chiamata che vuoi annullare.
Una richiesta riuscita restituisce un codice 200 OK con l'oggetto della chiamata aggiornato. Il status dell'oggetto della chiamata è cancelled quando la chiamata era in attesa dell'orario programmato o stava entrando o era in attesa nella coda, e completed quando annulli un richiamo dell'agente virtuale attivo che ha già effettuato il primo tentativo di composizione.
Se la chiamata è già stata annullata, la richiesta restituisce 204 No Content con un corpo vuoto. Una richiesta per una chiamata che non è già andata a buon fine per un motivo diverso dall'annullamento o che si trova in uno stato che non può essere annullato restituisce 400.
Annulla più chiamate programmate
Per annullare più chiamate programmate, chiama il numero PATCH
https://<subdomain>.<domain>/apps/api/v1/calls/scheduled/cancel. Includi un corpo della richiesta contenente un array call_ids degli ID chiamata per le chiamate da annullare.
Vedi l'esempio di codice che segue:
{
"call_ids": [123, 456, 789]
}
Una richiesta riuscita restituisce un 202 Accepted con un'intestazione della risposta Location che punta a una risorsa job di cui puoi eseguire il polling per il completamento. La risposta 202 Accepted non significa che tutte le chiamate siano già state annullate. Segui l'intestazione Location per confermare il completamento e ispezionare gli errori parziali.
Utilizza le chiamate di richiamata con i CRM
Puoi utilizzare l'API per le chiamate di richiamata con le integrazioni CRM di Salesforce, Zendesk e ServiceNow.
Comportamento generale del callback
Se utilizzi un CRM supportato (Salesforce, Zendesk o ServiceNow), le seguenti condizioni influiscono sul comportamento della richiamata programmata:
Un record è aperto e ha già una chiamata programmata attiva: se una ricerca dell'ID ticket indica che il record è aperto e ha già una chiamata programmata attiva, la chiamata non viene programmata. Il seguente commento è allegato al record CRM:
A scheduled call was not created because the record already has an active scheduled call.Impossibile raggiungere il CRM: se una ricerca dell'ID ticket indica che il CRM non può essere raggiunto, la chiamata viene annullata. Il seguente commento è allegato al record CRM:
A scheduled call was canceled because the CRM was unreachable.
Comportamento di callback con record chiusi
Il modo in cui vengono gestite le chiamate di richiamata per i record chiusi varia a seconda del CRM che utilizzi:
Utenti di Zendesk e ServiceNow: se una ricerca dell'ID ticket indica che il record è chiuso, la chiamata non viene pianificata. Il seguente commento è allegato al record CRM:
A scheduled call was not created because the record is closed.Utenti di Salesforce: consulta Chiamate di richiamata con Salesforce per configurare il modo in cui la tua istanza gestisce le chiamate pianificate per i record chiusi.
Chiamate di callback con Salesforce
Se hai integrato la piattaforma CCAI con Salesforce, puoi configurare il modo in cui l'istanza gestisce le chiamate programmate per i record chiusi. Di seguito sono riportate le opzioni di configurazione per le integrazioni di Salesforce:
Non controllare lo stato del record
Puoi configurare la piattaforma CCAI in modo che non controlli lo stato del record prima di effettuare una chiamata programmata. Con questa configurazione, la chiamata viene effettuata come pianificato, indipendentemente dal fatto che il record sia aperto o chiuso.
Per configurare CCAI Platform in modo che non controlli lo stato del record, segui questi passaggi:
Nel portale della piattaforma CCAI, fai clic su Impostazioni > Gestione delle operazioni. Se non vedi il menu Impostazioni, fai clic su Menu.
Vai a Dettagli sulla creazione dei record CRM > Opzioni per i record chiusi quando avvii una chiamata pianificata tramite API.
Seleziona Don't check the record status. Avvia sempre la chiamata pianificata tramite API.
Fai clic su Salva impostazioni generali.
Controlla lo stato dei record e riapri i record chiusi
Puoi configurare la piattaforma CCAI in modo che controlli lo stato del record prima di effettuare una chiamata programmata e riapra i record chiusi. Con questa configurazione, se lo stato del record è chiuso, vengono eseguite le seguenti azioni:
La chiamata viene effettuata come programmato.
Il record è stato riaperto.
Il seguente commento è allegato al record CRM:
The record was reopened at the time of a scheduled call.
Per configurare CCAI Platform in modo che controlli lo stato dei record e riapra quelli chiusi, segui questi passaggi:
Nel portale della piattaforma CCAI, fai clic su Impostazioni > Gestione delle operazioni. Se non vedi il menu Impostazioni, fai clic su Menu.
Vai a Dettagli sulla creazione dei record CRM > Opzioni per i record chiusi quando avvii una chiamata pianificata tramite API.
Seleziona Controlla lo stato del record. Se il record è chiuso > Riapri il record.
Fai clic su Salva impostazioni generali.
Controlla lo stato del record e annulla le chiamate programmate per i record chiusi
Puoi configurare la piattaforma CCAI in modo che controlli lo stato del record prima di effettuare una chiamata programmata e annulli le chiamate programmate per i record chiusi. Con questa configurazione, se lo stato del record è chiuso, vengono eseguite le seguenti azioni:
La chiamata programmata è stata annullata.
Il seguente commento è allegato al record CRM:
A scheduled call was canceled because the record is closed.
Per configurare CCAI Platform in modo che controlli lo stato dei record e annulli le chiamate programmate per i record chiusi, segui questi passaggi:
Nel portale della piattaforma CCAI, fai clic su Impostazioni > Gestione delle operazioni. Se non vedi il menu Impostazioni, fai clic su Menu.
Vai a Dettagli sulla creazione dei record CRM > Opzioni per i record chiusi quando avvii una chiamata pianificata tramite API.
Seleziona Controlla lo stato del record. Se il record è chiuso > Annulla la chiamata programmata.
Fai clic su Salva impostazioni generali.