Endpoint di chiamata

Gli endpoint API di chiamata forniscono l'accesso agli oggetti di chiamata. Viene creato un oggetto chiamata per ogni chiamata effettuata da e verso Contact Center AI Platform (CCAI Platform).

Di seguito sono riportati gli endpoint API di chiamata:

Oggetto chiamata

Di seguito è riportato un esempio di oggetto di chiamata:

[
  {
    "id": 0,
    "parent_id": 0,
    "lang": "en",
    "call_type": "Voice Scheduled (API)",
    "status": "scheduled",
    "created_at": "2018-06-07T19:49:52.896Z",
    "queued_at": "2018-06-07T19:49:52.896Z",
    "assigned_at": "2018-06-07T19:49:52.896Z",
    "connected_at": "2018-06-07T19:49:52.896Z",
    "ends_at": "2018-06-07T19:49:52.896Z",
    "scheduled_at": "2018-06-07T19:49:52.896Z",
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": 0,
    "has_feedback": true,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": "string",
    "out_ticket_url": "string",
    "verified": true,
    "recording_url": "string",
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_details": "string",
    "fail_reason": "nothing",
    "support_number": "string",
    "selected_menu": {
      "id": 0,
      "name": "string",
      "parent_id": 0,
      "position": 0,
      "deleted": true,
      "hidden": "string",
      "menu_type": "ivr_menu",
      "output_msg": "string"
    },
    "menu_path": {
      "items_count": 0,
      "name": "string",
      "materialized_path": "string"
    },
    "agent_info": {
      "id": 0,
      "name": "string",
      "last_name": "string",
      "first_name": "string",
      "agent_number": "string",
      "avatar_url": "string"
    },
    "end_user": {
      "id": 0,
      "identifier": "string",
      "out_contact_id": "string"
    },
    "photos": [
      {
        "id": 0,
        "photo_type": "photo",
        "url": "string"
      }
    ],
    "videos": [
      {
        "id": 0,
        "url": "string"
      }
    ],
    "transfers": [
      {
        "id": 0,
        "status": "transferring",
        "fail_reason": "nothing",
        "created_at": "2018-06-07T19:49:52.896Z",
        "from_menu": {
          "items_count": 0,
          "name": "string",
          "materialized_path": "string"
        },
        "to_menu": {
          "items_count": 0,
          "name": "string",
          "materialized_path": "string"
        },
        "from_agent": {
          "id": 0,
          "name": "string",
          "last_name": "string",
          "first_name": "string",
          "agent_number": "string",
          "avatar_url": "string"
        },
        "to_agent": {
          "id": 0,
          "name": "string",
          "last_name": "string",
          "first_name": "string",
          "agent_number": "string",
          "avatar_url": "string"
        }
      }
    ],
    "participants": [
      {
        "id": 0,
        "type": "end_user",
        "status": "waiting",
        "call_id": 0,
        "user_id": 0,
        "end_user_id": 0,
        "call_duration": 0,
        "hold_duration": 0,
        "connected_at": "2018-06-07T19:49:52.896Z",
        "ended_at": "2018-06-07T19:49:52.896Z",
        "fail_reason": "nothing"
      }
    ]
  }
]

Definizioni degli stati delle chiamate

Il campo dello stato può essere in uno dei seguenti stati:

Stato della chiamata Descrizione
Selezione Stato che si verifica quando un utente finale ha chiamato il contact center, ma sta ancora navigando tra le opzioni di menu prima di essere inserito in un menu foglia.
In coda Stato che si verifica dopo che l'utente finale ha selezionato un nodo del menu foglia e ha avviato una richiesta di chiamata da trasmettere in deltcast o multicast a un agente.
Assegnata Stato che si verifica quando un agente viene selezionato per ricevere la chiamata dell'utente finale. Questo accade quando un agente risponde a una chiamata.
Connessione in corso… Stato che si verifica dopo l'assegnazione di un agente e l'instaurazione di una connessione tra l'utente finale e l'agente.
Connesso Stato che si verifica quando la chiamata ha stabilito una connessione e l'agente e l'utente finale vengono entrambi inseriti in una chiamata.
Terminato Stato che si verifica quando una chiamata termina dopo essere stata connessa.
Non riuscito Stato che si verifica quando una chiamata termina prima di essere connessa correttamente. Verrà inoltre fornito un motivo dell'errore per ulteriori dettagli.
Cambiamento modalità in corso Stato che si verifica quando una chiamata non va a buon fine durante il tentativo di connessione e CCAI Platform tenta di connettere la chiamata con un provider VOIP diverso.
Recuperato Stato che si verifica quando viene richiamata una chiamata non riuscita. Questa nuova chiamata è una chiamata secondaria rispetto a quella originale. Note recuperate che indicano che il callback è terminato senza errori.
Pianificato Stato che si verifica quando un utente finale ha programmato una chiamata futura utilizzando In-Web o In-App.
Solo azione Stato che si verifica quando una chiamata gestita dal provider di telefonia del nostro cliente viene connessa al nostro SDK per iOS o Android.
Azione completata Stato che si verifica quando una chiamata gestita dal provider di telefonia del nostro cliente viene connessa al nostro SDK per iOS o Android e termina
Deviata Stato che si verifica in base alla configurazione per le code in sovraccapacità o le chiamate fuori orario. Le opzioni di deviazione includono, tra le altre, la segreteria e la programmazione di una chiamata. La deviazione varia in base al canale (in-app, IVR, in-web)
Segreteria Stato che si verifica quando un utente finale viene indirizzato a un'opzione di segreteria e sceglie di lasciare un messaggio vocale da ascoltare in un secondo momento. Questo stato è presente quando l'utente finale sta lasciando il messaggio vocale
Messaggio vocale ricevuto Stato che si verifica dopo che un utente finale ha lasciato un messaggio vocale e un agente non lo ha ascoltato
Lettura dei messaggi vocali Stato che si verifica quando un agente ha aperto il messaggio vocale da ascoltare.

Definizioni dei tipi di chiamata

Il campo call_type può essere solo uno dei seguenti valori:

Tipo di chiamata Descrizione
Voice Outbound (API) Chiamata effettuata dall'API Chiamata in uscita.
Voice Inbound (API) Chiamata effettuata dall'API Incoming Call.
Voice Scheduled (API) Chiamata effettuata dall'API Scheduled Call.

Codici di risposta dell'API comuni

Di seguito sono riportate le risposte dell'API più comuni:

Codice di risposta Significato
201 La richiesta API è andata a buon fine e creerà una chiamata
202 La richiesta API è andata a buon fine, ma è necessario un intervento manuale all'interno del widget per completare l'azione
400 tipo di chiamata non valido: assicurati che call_type sia supportato
400 L'agente non è disponibile per rispondere a questa chiamata
400 Parametro mancante: verifica che siano stati aggiunti i parametri obbligatori
404 Risorsa non trovata. Controlla il sottodominio

Chiamata in uscita - end_user_number

Parametro Obbligatorio Tipo di dati Definizione
call_tye VERO Stringa Chiama tye per creare. "Voice Outbound (API)", "OutboundCall" (ritirato) sono disponibili per il momento
agent_email VERO Stringa Indirizzo email dell'agente a cui verrà assegnata la chiamata in uscita.
ticket_id FALSE Stringa ID ticket CRM e chiamerà l'utente finale associato al ticket.
end_user_number FALSE Stringa Numero di telefono dell'utente finale che verrà composto. ticket_id ha una priorità più alta di end_user_number.
outbound_number FALSE Stringa Numero in uscita nel formato corretto, gestito da Impostazioni > Numeri di telefono > Gestione dei numeri di telefono. Se il campo è vuoto, verrà utilizzato il numero in uscita predefinito
lang FALSE Stringa Lingua della chiamata. Utilizza i codici ISO 639-1. (Valore predefinito: "en")

Endpoint:

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/calls

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "outbound_number": "+1 760-867-5309",
    "end_user_number": "123123",
    "lang": "en"
}

Esempio di richiesta e risposte

Le sezioni seguenti forniscono esempi di richieste all'endpoint.

Errore : l'agente non è disponibile per rispondere a questa chiamata

Questo esempio mostra lo scenario di errore quando l'agente non è disponibile per ricevere la chiamata.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
Risposta: Errore : l'agente non è disponibile per rispondere a questa chiamata
{
    "message": "Agent is not available to take this call"
}

Codice di stato: 400

Crea una chiamata in uscita con il numero dell'utente finale

Questo esempio mostra come effettuare una chiamata in uscita per un numero di utente finale specifico.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 859-657-9625",
    "outbound_number": "+1 339-219-5276",
    "lang": "en"
}
Risposta: crea una chiamata in uscita con end_user_number
{
    "id": 397,
    "lang": "en",
    "call_type": "Voice Outbound (API)",
    "status": "assigned",
    "created_at": "2019-06-07T01:27:30.406Z",
    "queued_at": null,
    "assigned_at": "2019-06-07T01:27:30.441Z",
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": null,
    "menu_path": null,
    "agent_info": {
        "id": 1,
        "agent_number": null,
        "name": "Admin UJET",
        "last_name": "UJET",
        "first_name": "Admin",
        "avatar_url": "https://somedomain.com/avatar.jpg"
    },
    "end_user": null,
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 610,
            "type": "agent",
            "status": "waiting",
            "call_id": 397,
            "user_id": 1,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        },
        {
            "id": 611,
            "type": "end_user",
            "status": "waiting",
            "call_id": 397,
            "user_id": null,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": null,
    "offer_events": [],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

Codice di stato: 201

Crea una chiamata in uscita con l'ID ticket

Questo esempio mostra la creazione di una chiamata in uscita con un ID ticket specifico.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "ticket_id": "71450",
    "outbound_number": "+1 339-219-5276",
    "lang": "en"
}
Risposta: Crea una chiamata in uscita con ticket_id
{
    "id": 398,
    "lang": "en",
    "call_type": "Voice Outbound (API)",
    "status": "assigned",
    "created_at": "2019-06-07T01:28:47.955Z",
    "queued_at": null,
    "assigned_at": "2019-06-07T01:28:47.971Z",
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": "71450",
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": null,
    "menu_path": null,
    "agent_info": {
        "id": 1,
        "agent_number": null,
        "name": "Admin UJET",
        "last_name": "UJET",
        "first_name": "Admin",
        "avatar_url": "https://somedomain.com/avatar.png"
    },
    "end_user": {
        "id": 67,
        "identifier": null,
        "out_contact_id": "381630957514"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 612,
            "type": "agent",
            "status": "waiting",
            "call_id": 398,
            "user_id": 1,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        },
        {
            "id": 613,
            "type": "end_user",
            "status": "waiting",
            "call_id": 398,
            "user_id": null,
            "end_user_id": 67,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": null,
    "offer_events": [],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

Codice di stato: 201

Errore : ID ticket o numero dell'utente finale obbligatorio

Questo esempio mostra il caso di errore in cui l'ID ticket o il numero dell'utente finale sono obbligatori, ma non vengono forniti.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

Risposta: Errore : ticket_id o end_user_number obbligatorio

{
    "message": "ticket_id or end_user_number required"
}

Codice di stato: 400

Errore : l'indirizzo email dell'agente non è valido

Questo esempio mostra l'errore che si verifica quando l'indirizzo email fornito per un agente non è valido.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

Risposta: Errore : indirizzo email dell'agente non valido

{
    "message": "Not a valid agent email"
}

Codice di stato: 400

Errore : l'indirizzo email dell'agente è obbligatorio

Questo esempio mostra l'errore che si verifica quando non viene fornito un indirizzo email per l'agente.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

Risposta: Errore : l'indirizzo email dell'agente è obbligatorio

{
    "message": "Agent email required"
}

Codice di stato: 400

Errore : l'agente non dispone dell'accesso per effettuare chiamate

Questo esempio mostra l'errore che si verifica quando l'agente specificato non è autorizzato a effettuare chiamate in uscita.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
Risposta: Errore : l'agente non dispone dell'accesso per effettuare chiamate
{
    "message": "Agent does not have access to make calls"
}

Codice di stato: 400

Errore : end_user_number non è nel formato corretto

Questo esempio mostra lo scenario di errore in cui il numero dell'utente finale fornito non è formattato correttamente.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
Risposta: Errore : end_user_number non è nel formato corretto
{
    "message": "end_user_number is not well-formed"
}

Codice di stato: 400

Errore : contatto non trovato

Questo esempio mostra lo scenario di errore in cui il contatto fornito non esiste.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "ticket_id": 1,
    "lang": "en"
}
Risposta: Errore : contatto non trovato
{
    "message": "Contact not found"
}

Codice di stato: 400

Accettata : è necessario scegliere un numero in uscita

In questo esempio, la chiamata in uscita viene accettata, ma l'agente deve scegliere il numero in uscita da utilizzare prima che la chiamata venga effettuata.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "outbound_number": "+1 760-867-5309",
    "end_user_number": "123123",
    "lang": "en"
}
Risposta
{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

Codice di stato: 200

Errore : tipo di chiamata non valido

Questo esempio mostra lo scenario di errore in cui il tipo di chiamata fornito non è valido.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
Risposta: Errore : tipo di chiamata non valido
{
    "message": "Invalid call type"
}

Codice di stato: 400

Richiedi l'adattatore per chiamate da più numeri in uscita

In questo scenario, l'adattatore per chiamate viene richiesto con più numeri in uscita.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "outbound_number": "+1 760-867-5309",
    "end_user_number": "123123",
    "lang": "en"
}
Risposta
{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 859-657-9625",
    "lang": "en"
}

Codice di stato: 200

Accettato : l'agente deve effettuare una chiamata in uscita con l'ID ticket

Questo esempio mostra una richiesta in cui l'agente deve effettuare una chiamata in uscita in base all'ID ticket fornito.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

Codice di stato: 202

Chiamata in uscita - ticket_id

Parametro Obbligatorio Tipo di dati Definizione
call_type VERO Stringa Tipo di chiamata da creare. "Voice Outbound (API)", "OutboundCall" (ritirato) sono disponibili per il momento
agent_email VERO Stringa Indirizzo email dell'agente a cui verrà assegnata la chiamata in uscita.
ticket_id FALSE Stringa ID ticket CRM e chiamerà l'utente finale associato al ticket.
end_user_number FALSE Stringa Numero di telefono dell'utente finale che verrà composto. ticket_id ha una priorità più alta di end_user_number.
outbound_number FALSE Stringa Numero in uscita nel formato corretto, gestito da Impostazioni > Numeri di telefono > Gestione dei numeri di telefono. Se il campo è vuoto, verrà utilizzato il numero in uscita predefinito
lang FALSE Stringa Lingua della chiamata. Utilizza i codici ISO 639-1. (Valore predefinito: "en")

Endpoint:

Method: POST
Type: RAW
URL: https://{subdomain}.{domain}​/apps/api/v1/calls

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-867-5309",
    "ticket_id": "123123",
    "lang": "en"
}

Esempio di richiesta e risposte

Le sezioni seguenti forniscono esempi di richieste all'endpoint.

Errore : ID ticket o numero dell'utente finale obbligatorio

In questo esempio, lo scenario di errore dell'ID ticket o del numero dell'utente finale è mancante, ma obbligatorio.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

Risposta: Errore : ticket_id o end_user_number obbligatorio

{
    "message": "ticket_id or end_user_number required"
}

Codice di stato: 400

Errore : l'indirizzo email dell'agente è obbligatorio

In questo esempio mostriamo lo scenario di errore in cui l'email dell'agente non viene fornita, ma è obbligatoria.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
Risposta: Errore : l'indirizzo email dell'agente è obbligatorio
{
    "message": "Agent email required"
}

Codice di stato: 400

Crea una chiamata in uscita con il numero dell'utente finale

In questo esempio mostriamo come creare una chiamata in uscita fornendo il numero dell'utente finale.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 859-657-9625",
    "outbound_number": "+1 339-219-5276",
    "lang": "en"
}
Risposta: crea una chiamata in uscita con end_user_number
{
    "id": 397,
    "lang": "en",
    "call_type": "Voice Outbound (API)",
    "status": "assigned",
    "created_at": "2019-06-07T01:27:30.406Z",
    "queued_at": null,
    "assigned_at": "2019-06-07T01:27:30.441Z",
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reaso": "not_voicemail",
    "deflection": "n_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": null,
    "menu_path": null,
    "agent_info": {
        "id": 1,
        "agent_number": null,
        "name": "Admin UJET",
        "last_name": "UJET",
        "first_name": "Admin",
        "avatar_url": "https://somedomain.com/default-profile.png"
    },
    "end_user": null,
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 610,
            "type": "agent",
            "status": "waiting",
            "call_id": 397,
            "user_id": 1,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        },
        {
            "id": 611,
            "type": "end_user",
            "status": "waiting",
            "call_id": 397,
            "user_id": null,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": null,
    "offer_events": [],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

Codice di stato: 201

Errore : tipo di chiamata non valido

In questo esempio mostriamo lo scenario di errore in cui il tipo di chiamata fornito non è valido.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "ScheduledCall",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
Risposta: Errore : tipo di chiamata non valido
{
    "message": "Invalid call type"
}

Codice di stato: 400

Richiedi l'adattatore per chiamate da più numeri in uscita

In questo esempio mostriamo come richiedere all'adattatore per chiamate più numeri di telefono in uscita.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 859-657-9625",
    "lang": "en"
}

Codice di stato: 202

Accettato : l'agente deve effettuare una chiamata in uscita con l'ID ticket

In questo esempio mostriamo come effettuare una chiamata in uscita con un ID ticket e l'agente accetta la richiesta.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json
***Corpo:*** ```json { "call_type": "Voice Outbound (API)", "agent_email": "allen@somedomain.com", "end_user_number": "+1 205-123-4567", "lang": "en" } ``` ***Codice di stato:*** 202 #### Errore : l'agente non ha accesso per effettuare chiamate In questo esempio mostriamo lo scenario di errore in cui viene inviata una richiesta di creazione di una chiamata, ma l'agente non ha accesso per poter effettuare chiamate in uscita. ##### Richiesta ***Intestazioni:***
Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
Risposta: Errore : l'agente non dispone dell'accesso per effettuare chiamate
{
    "message": "Agent does not have access to make calls"
}

Codice di stato: 400

Crea una chiamata in uscita con l'ID ticket.

In questo esempio mostriamo lo scenario di creazione di una chiamata in uscita con un ID ticket.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "ticket_id": "71450",
    "outbound_number": "+1 339-219-5276",
    "lang": "en"
}
Risposta: Crea una chiamata in uscita con ticket_id
{
    "id": 398,
    "lang": "en",
    "call_type": "Voice Outbound (API)",
    "status": "assigned",
    "created_at": "2019-06-07T01:28:47.955Z",
    "queued_at": null,
    "assigned_at": "2019-06-07T01:28:47.971Z",
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": "71450",
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": null,
    "menu_path": null,
    "agent_info": {
        "id": 1,
        "agent_number": null,
        "name": "Admin UJET",
        "last_name": "UJET",
        "first_name": "Admin",
        "avatar_url": "https://somedomain.com/default-profile.png"
    },
    "end_user": {
        "id": 67,
        "identifier": null,
        "out_contact_id": "381630957514"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 612,
            "type": "agent",
            "status": "waiting",
            "call_id": 398,
            "user_id": 1,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        },
        {
            "id": 613,
            "type": "end_user",
            "status": "waiting",
            "call_id": 398,
            "user_id": null,
            "end_user_id": 67,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": null,
    "offer_events": [],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

Codice di stato: 201

Accettata : è necessario scegliere un numero in uscita

In questo esempio mostriamo lo scenario in cui viene creata una richiesta di chiamata in uscita con la necessità di scegliere un numero in uscita, che viene poi accettata.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

Codice di stato: 202

Errore : l'agente non è disponibile per rispondere a questa chiamata

In questo esempio mostriamo lo scenario di errore in cui viene creata una chiamata, ma l'agente non è disponibile per accettarla.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
Risposta: Errore : l'agente non è disponibile per rispondere a questa chiamata
{
    "message": "Agent is not available to take this call"
}

Codice di stato: 400

Errore : il numero dell'utente finale non è nel formato corretto

In questo esempio mostriamo lo scenario di errore in cui il numero di telefono dell'utente finale fornito non è formattato correttamente.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
Risposta: Errore : end_user_number non è nel formato corretto
{
    "message": "end_user_number is not well-formed"
}

Codice di stato: 400

Errore : l'indirizzo email dell'agente non è valido

In questo esempio mostriamo lo scenario di errore in cui l'indirizzo email dell'agente fornito non è valido.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
Risposta: Errore : indirizzo email dell'agente non valido
{
    "message": "Not a valid agent email"
}

Codice di stato: 400

Errore : contatto non trovato

In questo esempio mostriamo lo scenario di errore in cui non è stato possibile individuare il contatto fornito.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "ticket_id": 1,
    "lang": "en"
}
Risposta: Errore : contatto non trovato
{
    "message": "Contact not found"
}

Codice di stato: 400

Chiamata in arrivo

Parametro Obbligatorio Tipo di dati Definizione
call_type VERO Stringa Tipo di chiamata da creare. Utilizza "Voice Inbound (API)" o "IncomingCall" (deprecato) per creare una chiamata in arrivo.
menu_id VERO Numero intero L'ID del menu a cui attribuire la chiamata. Sono accettati solo gli ID dei menu IVR e web.
end_user_number VERO Stringa Il numero di telefono dell'utente finale che verrà composto. Se vengono passati sia un ticket_id sia un end_user_number, il ticket_id avrà la precedenza.
lang FALSE Stringa Lingua della chiamata. Utilizza i codici ISO 639-1. (Valore predefinito: "en")
ticket_id FALSE Stringa ID ticket CRM. Verrà composto il numero di telefono dell'utente finale associato al ticket. Se vengono passati sia un ticket_id sia un end_user_number, il ticket_id avrà la precedenza.
outbound_number FALSE Stringa Il numero di telefono in uscita da utilizzare per la chiamata. Se l'input non viene fornito o non è valido, verrà utilizzato il numero di telefono in uscita globale predefinito. I numeri in uscita vengono gestiti da Impostazioni > Coda > MODIFICA / VISUALIZZA > Seleziona una coda > Numeri di telefono in uscita.
recording_permission FALSE Stringa Il valore viene valutato solo se la funzionalità "Opzioni di registrazione delle chiamate" è impostata su "Chiedi all'utente l'autorizzazione per la registrazione". Configurabile in Impostazioni > Coda > MODIFICA / VISUALIZZA > Seleziona una coda > Opzioni di registrazione delle chiamate. Se il valore è "recording_permission_not_asked" (predefinito) o "recording_permission_denied", la chiamata non verrà registrata. Se il valore è "recording_permission_granted", la chiamata verrà registrata.

Endpoint:

Method: POST
Type: RAW
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/calls

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "ticket_id": "76517",
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}

Esempio di richiesta e risposte

Le sezioni seguenti forniscono esempi di richieste all'endpoint.

Errore : il numero dell'utente finale non è nel formato corretto

In questo esempio mostriamo lo scenario di errore in cui viene creata una chiamata in arrivo, ma il numero dell'utente finale fornito non è nel formato corretto.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 999-657-12",
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : end_user_number non è nel formato corretto
{
    "message": "end_user_number is not well formed"
}

Codice di stato: 400

Errore : il menu è in stato di "reindirizzamento manuale", impossibile accettare chiamate

In questo esempio mostriamo lo scenario di errore in cui una chiamata viene instradata a un ID menu, ma il menu è in stato di reindirizzamento manuale e, di conseguenza, non può ricevere chiamate in arrivo.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : il menu è in stato di "reindirizzamento manuale", non è possibile accettare chiamate
{
    "message": "Menu is in 'manual redirection' state, can't accept calls"
}

Codice di stato: 400

Errore : tipo di chiamata non valido

In questo esempio mostriamo lo scenario di errore in cui viene creata una chiamata in arrivo, ma il tipo di chiamata fornito non è valido.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "InvalidCallType",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : tipo di chiamata non valido
{
    "message": "Invalid call type"
}

Codice di stato: 400

Errore : l'ID menu è obbligatorio

In questo esempio mostriamo lo scenario di errore in cui viene creata una chiamata in arrivo, ma l'ID menu fornito non è valido.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : menu_id è obbligatorio
{
    "message": "menu_id is required"
}

Codice di stato: 400

Errore : sono consentiti solo gli ID menu IVR e mobile

In questo esempio mostriamo lo scenario di errore in cui viene creata una chiamata in arrivo, ma l'ID menu fornito non è un ID menu IVR o mobile.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 50,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : sono consentiti solo gli ID IVR e dei menu mobile
{
    "message": "Only IVR and mobile menu IDs are permitted"
}

Codice di stato: 400

Crea una chiamata in arrivo con il numero dell'utente finale

Questo esempio mostra come creare una chiamata in arrivo con un numero di utente finale specifico.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+82-10-6861-2345",
    "recording_permission": "recording_permission_granted"
}
Risposta: Crea una chiamata in arrivo con end_user_number
{
    "id": 515,
    "lang": "en",
    "call_type": "Voice Inbound (API)",
    "status": "queued",
    "created_at": "2019-09-10T00:19:14.000Z",
    "queued_at": "2019-09-10T00:19:14.421Z",
    "assigned_at": null,
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": {
        "id": 9,
        "name": "Lock Star",
        "parent_id": null,
        "position": 0,
        "deleted": false,
        "menu_type": "ivr_menu",
        "output_msg": "You selected Lock Star.",
        "hidden": false
    },
    "menu_path": {
        "items_count": 1,
        "name": "Lock Star",
        "materialized_path": "9"
    },
    "agent_info": null,
    "end_user": {
        "id": 75,
        "identifier": null,
        "out_contact_id": "389391400633"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 820,
            "type": "end_user",
            "status": "waiting",
            "call_id": 515,
            "user_id": null,
            "end_user_id": 75,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": "cascade",
    "offer_events": [
        {
            "casting_time": "2019-09-10T00:19:14.000Z",
            "group": "Group 1"
        }
    ],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

Codice di stato: 201

Errore : il menu è in stato "Fuori orario", non è possibile accettare chiamate in arrivo

Questo esempio mostra l'errore quando l'ID menu fornito è nello stato di fuori orario.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : il menu è in stato "fuori orario", impossibile accettare chiamate in arrivo
{
    "message": "Menu is in 'after hours' state, can't accept incoming calls"
}

Codice di stato: 400

Errore : la lingua non è disponibile

Questo esempio mostra la richiesta di errore quando la lingua specificata non è disponibile.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Inbound (API)",
    "lang": "fr",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : la lingua non è disponibile
{
    "message": "Language 'fr' is not available"
}

Codice di stato: 400

Crea una chiamata in arrivo con l'ID ticket

Questo esempio mostra la richiesta di creazione di una chiamata in arrivo con un ID ticket associato.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "ticket_id": "76517",
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Risposta: crea una chiamata in arrivo con ticket_id
{
    "id": 519,
    "lang": "en",
    "call_type": "Voice Inbound (API)",
    "status": "queued",
    "created_at": "2019-09-10T05:12:26.000Z",
    "queued_at": "2019-09-10T05:12:26.295Z",
    "assigned_at": null,
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "out_ticket_id": "76517",
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": {
        "id": 9,
        "name": "Lock Star",
        "parent_id": null,
        "position": 0,
        "deleted": false,
        "menu_type": "ivr_menu",
        "output_msg": "You selected Lock Star.",
        "hidden": false
    },
    "menu_path": {
        "items_count": 1,
        "name": "Lock Star",
        "materialized_path": "9"
    },
    "agent_info": null,
    "end_user": {
        "id": 75,
        "identifier": null,
        "out_contact_id": "389391400633"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 826,
            "type": "end_user",
            "status": "waiting",
            "call_id": 519,
            "user_id": null,
            "end_user_id": 75,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": "cascade",
    "offer_events": [
        {
            "casting_time": "2019-09-10T05:12:26.000Z",
            "group": "Group 1"
        }
    ],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

Codice di stato: 201

Errore : lingua non trovata

Questo esempio mostra l'errore quando la lingua fornita non viene trovata.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Inbound (API)",
    "lang": "xy",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : lingua non trovata
{
    "message": "Language 'xy' is not found"
}

Codice di stato: 400

Errore : menu_id non trovato

Questo esempio mostra l'errore quando l'ID menu fornito non viene trovato.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9999,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : menu_id non trovato
{
    "message": "menu_id 9999 is not found"
}

Codice di stato: 400

Errore : menu_id non è nel formato corretto

Questo esempio mostra l'errore che si verifica quando l'ID menu fornito non è corretto.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": "menu_999",
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : menu_id non è nel formato corretto
{
    "message": "menu_id is not well formed"
}

Codice di stato: 400

Errore : il numero dell'utente finale è obbligatorio

In questo esempio mostriamo lo scenario di errore in cui viene creata una chiamata in arrivo, ma non è stato fornito il numero di telefono dell'utente finale.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : end_user_number è obbligatorio
{
    "message": "end_user_number is required"
}

Codice di stato: 400

Chiamata programmata

Parametro Obbligatorio Tipo di dati Definizione
call_type VERO Stringa Tipo di chiamata da creare. Utilizza "Voice Scheduled (API)" o "ScheduledCall" (deprecato) per creare una chiamata programmata.
menu_id VERO Numero intero L'ID del menu a cui attribuire la chiamata. Sono accettati solo gli ID dei menu per dispositivi mobili e web.
call_id FALSE Numero intero ID della chiamata precedente, che verrà collegata come chiamata principale della nuova chiamata programmata creata. Quando viene utilizzato l'ID chiamata, menu_id può essere facoltativo.
end_user_number VERO Stringa Il numero di telefono dell'utente finale che verrà composto. Se vengono passati sia un ticket_id sia un end_user_number, il ticket_id avrà la precedenza.
lang FALSE Stringa Lingua della chiamata. Utilizza i codici ISO 639-1. (Valore predefinito: "en")
ticket_id FALSE Stringa ID ticket CRM. Verrà composto il numero di telefono dell'utente finale associato al ticket. Se vengono passati sia un ticket_id sia un end_user_number, il ticket_id avrà la precedenza.
scheduled_at VERO Stringa Ora programmata della chiamata. Utilizza il formato ISO 8601 per un'ora futura valida.
recording_permission FALSE Stringa Il valore viene valutato solo se la funzionalità "Opzioni di registrazione delle chiamate" è impostata su "Chiedi all'utente l'autorizzazione per la registrazione". Configurabile in Impostazioni > Coda > MODIFICA / VISUALIZZA > Seleziona una coda > Opzioni di registrazione delle chiamate. Se il valore è "recording_permission_not_asked" (predefinito) o "recording_permission_denied", la chiamata non verrà registrata. Se il valore è "recording_permission_granted", la chiamata verrà registrata.

Endpoint:

Method: POST
Type: RAW
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/calls

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "ticket_id": "76517",
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}

Esempio di richiesta e risposte

Le sezioni seguenti forniscono esempi di richieste all'endpoint.

Errore : end_user_number non è nel formato corretto

Questo esempio mostra l'errore dovuto alla formattazione errata di end_user_number.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 999-657-12",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : end_user_number non è nel formato corretto
{
    "message": "end_user_number is not well formed"
}

Codice di stato: 400

Errore : il menu è in stato di "reindirizzamento manuale", impossibile accettare chiamate

Questo esempio mostra l'errore quando l'ID menu specificato è impostato sul reindirizzamento del menu e non è in grado di accettare chiamate.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : il menu è in stato di "reindirizzamento manuale", non è possibile accettare chiamate
{
    "message": "Menu is in 'manual redirection' state, can't accept calls"
}

Codice di stato: 400

Errore : tipo di chiamata non valido

Questo esempio mostra l'errore che si verifica quando viene effettuata una richiesta e il tipo di chiamata non è valido.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "InvalidCallType",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : tipo di chiamata non valido
{
    "message": "Invalid call type"
}

Codice di stato: 400

Errore : menu_id è obbligatorio

Questo esempio mostra la richiesta e la risposta quando un ID menu non viene fornito, ma è obbligatorio.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : menu_id è obbligatorio
{
    "message": "menu_id is required"
}

Codice di stato: 400

Errore : sono consentiti solo gli ID menu per dispositivi mobili e web

Questo esempio mostra una richiesta che non va a buon fine quando viene fornito un ID menu che non è un ID menu web o mobile.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 50,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : sono consentiti solo gli ID dei menu mobile e web
{
    "message": "Only mobile and web menu IDs are permitted"
}

Codice di stato: 400

Crea una chiamata programmata con l'ID menu

Questo esempio mostra come creare una chiamata programmata con un ID menu specifico.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+82-10-6861-2345",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Risposta: crea una chiamata programmata con l'ID menu
{
    "id": 515,
    "lang": "en",
    "call_type": "Voice Inbound (API)",
    "status": "queued",
    "created_at": "2019-09-10T00:19:14.000Z",
    "queued_at": null,
    "assigned_at": null,
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": {
        "id": 9,
        "name": "Lock Star",
        "parent_id": null,
        "position": 0,
        "deleted": false,
        "menu_type": "ivr_menu",
        "output_msg": "You selected Lock Star.",
        "hidden": false
    },
    "menu_path": {
        "items_count": 1,
        "name": "Lock Star",
        "materialized_path": "9"
    },
    "agent_info": null,
    "end_user": {
        "id": 75,
        "identifier": null,
        "out_contact_id": "389391400633"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 820,
            "type": "end_user",
            "status": "waiting",
            "call_id": 515,
            "user_id": null,
            "end_user_id": 75,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": "cascade",
    "offer_events": [
        {
            "casting_time": "2019-09-10T00:19:14.000Z",
            "group": "Group 1"
        }
    ],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

Codice di stato: 201

Crea una chiamata programmata con l'ID chiamata

Questo esempio mostra come creare una chiamata programmata con un ID chiamata specifico.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "call_id": 514,
    "end_user_number": "+82-10-6861-2345",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Risposta: crea una chiamata programmata con l'ID chiamata
{
    "id": 515,
    "lang": "en",
    "call_type": "Voice Inbound (API)",
    "status": "queued",
    "created_at": "2019-09-10T00:19:14.000Z",
    "queued_at": null,
    "assigned_at": null,
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": {
        "id": 9,
        "name": "Lock Star",
        "parent_id": null,
        "position": 0,
        "deleted": false,
        "menu_type": "ivr_menu",
        "output_msg": "You selected Lock Star.",
        "hidden": false
    },
    "menu_path": {
        "items_count": 1,
        "name": "Lock Star",
        "materialized_path": "9"
    },
    "agent_info": null,
    "end_user": {
        "id": 75,
        "identifier": null,
        "out_contact_id": "389391400633"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 820,
            "type": "end_user",
            "status": "waiting",
            "call_id": 515,
            "user_id": null,
            "end_user_id": 75,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": "cascade",
    "offer_events": [
        {
            "casting_time": "2019-09-10T00:19:14.000Z",
            "group": "Group 1"
        }
    ],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

Codice di stato: 201

Errore : il menu è in stato "Fuori orario", non è possibile accettare chiamate in arrivo

In questo esempio mostriamo lo scenario di errore in cui viene creata una chiamata programmata, ma il menu fornito è fuori orario e pertanto non può ricevere chiamate in arrivo.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : il menu è in stato "fuori orario", impossibile accettare chiamate in arrivo
{
    "message": "Menu is in 'after hours' state, can't accept incoming calls"
}

Codice di stato: 400

Errore : la lingua non è disponibile

Questo esempio mostra l'errore quando la lingua specificata non è valida.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "fr",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : la lingua non è disponibile
{
    "message": "Language 'fr' is not available"
}

Codice di stato: 400

Errore : lingua non trovata

In questo esempio mostriamo lo scenario di errore in cui viene creata una chiamata programmata, ma la lingua non è valida o non è disponibile.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "xy",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : lingua non trovata
{
    "message": "Language 'xy' is not found"
}

Codice di stato: 400

Errore : ID menu non trovato

In questo esempio mostriamo lo scenario di errore in cui viene creata una chiamata programmata, ma l'ID menu fornito non è valido e non viene trovato.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9999,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : ID menu non trovato
{
    "message": "menu_id 9999 is not found"
}

Codice di stato: 400

Errore : l'ID menu non è nel formato corretto

In questo esempio mostriamo lo scenario di errore in cui viene creata una chiamata programmata, ma l'ID menu fornito non è nel formato corretto.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": "menu_999",
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : menu_id non è nel formato corretto
{
    "message": "menu_id is not well formed"
}

Codice di stato: 400

Errore : il numero dell'utente finale è obbligatorio

In questo esempio mostriamo lo scenario di errore in cui viene creata una chiamata programmata, ma non viene fornito il numero dell'utente finale.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : end_user_number è obbligatorio
{
    "message": "end_user_number is required"
}

Codice di stato: 400

Errore : scheduled_at è obbligatorio

In questo esempio mostriamo lo scenario di errore in cui viene creata una chiamata pianificata, ma il valore scheduled_at manca, anche se è obbligatorio.

Richiesta

Headers:

Chiave Valore Descrizione
Content-Type application/json

Body:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Risposta: Errore : scheduled_at è obbligatorio
{
    "message": "scheduled_at is required"
}

Codice di stato: 400

Ricevi attributi dei dati riservati durante una chiamata

Endpoint

Method: GET
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/calls/:id/customer_flag

Esempio di richiesta e risposte

Questa sezione contiene una richiesta e una risposta di esempio per l'endpoint.

Operazione riuscita

Questo esempio mostra una chiamata riuscita.

Richiesta

Variabili URL

Chiave Valore Descrizione
id integer (Obbligatorio)
Risposta
{
    "verified_customer": "boolean",
    "bad_actor": "boolean",
    "repeat_customer": "boolean"
}

Codice di stato 0

Aggiorna gli attributi dei dati riservati durante una chiamata

Endpoint

Method: PATCH
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/calls/:id/customer_flag

Variabili URL

Chiave Valore Descrizione
id integer (Obbligatorio)

Body

{
    "verified_customer": "boolean",
    "bad_actor": "boolean",
    "repeat_customers": "boolean"
}

Passa i parametri dei dati agli agenti virtuali durante la sessione

Per utilizzare l'API Apps per passare i parametri dei dati agli agenti virtuali nel corso di una sessione di chiamata, consulta Passa i parametri dei dati agli agenti virtuali durante la sessione.