Appeler des points de terminaison

Les points de terminaison de l'API Call permettent d'accéder aux objets d'appel. Un objet d'appel est créé pour chaque appel passé vers et depuis Contact Center AI Platform (CCAI Platform).

Voici les points de terminaison de l'API d'appel :

Objet d'appel

Voici un exemple d'objet d'appel :

[
  {
    "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"
      }
    ]
  }
]

Définitions des états des appels

Le champ d'état peut avoir l'un des états suivants :

État de l'appel Description
Sélection… État qui se produit lorsqu'un utilisateur final a appelé le centre de contact, mais qu'il parcourt toujours les options du menu avant d'être placé dans un menu feuille.
En file d'attente État qui se produit une fois que l'utilisateur final a sélectionné un nœud de menu feuille et lancé une demande d'appel à deltacaster ou multicaster vers un agent.
Attribuée État qui se produit lorsqu'un agent est sélectionné pour recevoir l'appel de l'utilisateur final. Cela se produit lorsqu'un agent prend un appel.
Connexion État qui se produit après l'attribution d'un agent et l'établissement d'une connexion entre l'utilisateur final et l'agent.
Connecté État qui se produit lorsque l'appel a établi une connexion et que l'agent et l'utilisateur final sont tous deux placés dans un appel.
Terminé État qui se produit lorsqu'un appel se termine après avoir été connecté.
Échec État qui se produit lorsqu'un appel se termine avant d'avoir été connecté. Un motif d'échec sera également fourni pour plus de détails.
Changement de mode… État qui se produit lorsqu'un appel échoue lors de la tentative de connexion et que CCAI Platform tente de connecter l'appel avec un autre fournisseur VoIP.
Récupéré État qui se produit lorsqu'un appel ayant échoué est rappelé. Ce nouvel appel est un enfant de l'appel d'origine. Notes récupérées indiquant que le rappel s'est terminé sans erreur.
Programmée État qui se produit lorsqu'un utilisateur final a planifié un appel futur à l'aide d'In-Web ou d'In-App.
Action uniquement État qui se produit lorsqu'un appel géré par le fournisseur de téléphonie de notre client est connecté à notre SDK iOS ou Android.
Action uniquement terminée État qui se produit lorsqu'un appel géré par le fournisseur de téléphonie de notre client est connecté à notre SDK iOS ou Android et se termine
Dévié État qui se produit en fonction de la configuration des files d'attente en dépassement de capacité ou des appels hors des heures de travail. Les options de déviation incluent la messagerie vocale, la planification d'appels, etc. La déviation varie en fonction du canal (dans l'application, réponse vocale interactive, sur le Web).
Messagerie vocale État qui se produit lorsqu'un utilisateur final est redirigé vers une option de messagerie vocale et choisit de laisser un message vocal à écouter plus tard. Cet état est présent lorsque l'utilisateur final laisse un message vocal.
Message vocal reçu État qui se produit après qu'un utilisateur final a laissé un message vocal et qu'un agent ne l'a pas écouté
Accéder à la messagerie vocale État qui se produit lorsqu'un agent a ouvert le message vocal à écouter.

Définitions des types d'appels

Le champ call_type ne peut prendre que l'une des valeurs suivantes :

Type d'appel Description
Voice Outbound (API) Appel effectué à partir de l'API Outbound Call.
Voice Inbound (API) Appel effectué à partir de l'API Incoming Call.
Voice Scheduled (API) Appel passé à partir de l'API Scheduled Call.

Codes de réponse d'API courants

Voici les réponses de l'API les plus courantes :

Code de réponse Signification
201 La requête API a bien été effectuée et va créer un appel
202 La requête API a abouti, mais une intervention manuelle est requise dans le widget pour terminer l'action.
400 type d'appel non valide : assurez-vous que call_type est accepté
400 L'agent n'est pas disponible pour prendre cet appel
400 Paramètre manquant : vérifiez que les paramètres requis ont été ajoutés
404 Ressource introuvable : veuillez vérifier votre sous-domaine

Appel sortant - end_user_number

Paramètre Obligatoire Type de données Définition
call_tye TRUE Chaîne Appelez tye pour créer. "Voice Outbound (API)" et "OutboundCall" (obsolète) sont disponibles pour le moment.
agent_email TRUE Chaîne Adresse e-mail de l'agent qui sera affecté à l'appel sortant.
ticket_id FALSE Chaîne l'ID de la demande CRM, et le système appellera l'utilisateur final associé à la demande.
end_user_number FALSE Chaîne Numéro de téléphone de l'utilisateur final qui composera le numéro. ticket_id est prioritaire par rapport à end_user_number.
outbound_number FALSE Chaîne Numéro sortant correctement formé, géré depuis Paramètres > Numéros de téléphone > Gestion des numéros de téléphone. Le numéro sortant par défaut sera utilisé si ce champ est vide
lang FALSE Chaîne Langue de l'appel. Utilise les codes ISO 639-1. (Par défaut : "en")

Point de terminaison :

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

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

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

Exemples de requêtes et de réponses

Les sections suivantes fournissent des exemples de requêtes envoyées au point de terminaison.

Erreur : l'agent n'est pas disponible pour prendre cet appel

Cet exemple illustre le scénario d'échec lorsque l'agent n'est pas disponible pour recevoir l'appel.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
Réponse : Erreur : l'agent n'est pas disponible pour prendre cet appel
{
    "message": "Agent is not available to take this call"
}

Code d'état : 400

Créer un appel sortant avec le numéro de l'utilisateur final

Cet exemple montre comment passer un appel sortant pour un numéro d'utilisateur final spécifique.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "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"
}
Réponse : Créez un appel sortant avec 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"
}

Code d'état : 201

Créer un appel sortant avec un ID de demande d'assistance

Cet exemple montre comment créer un appel sortant avec un ID de ticket spécifique.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "ticket_id": "71450",
    "outbound_number": "+1 339-219-5276",
    "lang": "en"
}
Réponse : Créer un appel sortant avec 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"
}

Code d'état : 201

Erreur : ID de la demande ou numéro de l'utilisateur final requis

Cet exemple illustre le cas d'échec où l'ID du ticket ou le numéro de l'utilisateur final sont requis, mais non fournis.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

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

Réponse : Erreur : ticket_id ou end_user_number requis

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

Code d'état : 400

Erreur : Adresse e-mail de l'agent non valide

Cet exemple illustre l'échec lorsque l'adresse e-mail fournie pour un agent n'est pas valide.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

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

Réponse : Erreur : l'adresse e-mail de l'agent n'est pas valide

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

Code d'état : 400

Erreur : Veuillez indiquer l'adresse e-mail de l'agent

Cet exemple illustre l'échec lorsqu'aucune adresse e-mail n'est fournie pour l'agent.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

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

Réponse : Erreur : Adresse e-mail de l'agent requise

{
    "message": "Agent email required"
}

Code d'état : 400

Erreur : L'agent n'est pas autorisé à passer des appels

Cet exemple illustre l'échec lorsque l'agent spécifié n'est pas autorisé à passer des appels sortants.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
Réponse : Erreur : l'agent n'est pas autorisé à passer des appels
{
    "message": "Agent does not have access to make calls"
}

Code d'état : 400

Erreur : end_user_number n'est pas au bon format

Cet exemple illustre le scénario d'échec dans lequel le numéro d'utilisateur final fourni n'est pas correctement formaté.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
Réponse : Erreur : end_user_number n'est pas correctement formé
{
    "message": "end_user_number is not well-formed"
}

Code d'état : 400

Erreur : Contact introuvable

Cet exemple illustre le scénario d'échec dans lequel le contact fourni n'existe pas.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "ticket_id": 1,
    "lang": "en"
}
Réponse : Erreur : Contact introuvable
{
    "message": "Contact not found"
}

Code d'état : 400

Accepté : vous devez choisir un numéro pour les appels sortants

Dans cet exemple, l'appel sortant est accepté, mais l'agent doit choisir le numéro sortant à utiliser avant que l'appel ne soit passé.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

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

Code d'état : 200

Erreur : Type d'appel non valide

Cet exemple illustre le scénario d'échec dans lequel le type d'appel fourni n'est pas valide.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
Réponse : Erreur : Type d'appel non valide
{
    "message": "Invalid call type"
}

Code d'état : 400

Demander à l'adaptateur d'appel d'utiliser plusieurs numéros sortants

Dans ce scénario, l'adaptateur d'appel est invité à choisir parmi plusieurs numéros sortants.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

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

Code d'état : 200

Accepté : l'agent doit passer un appel sortant avec l'ID de la demande

Cet exemple illustre une requête dans laquelle l'agent doit passer un appel sortant en fonction de l'ID de ticket fourni.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

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

Code d'état : 202

Appel sortant - ticket_id

Paramètre Obligatoire Type de données Définition
call_type TRUE Chaîne Type d'appel à créer. "Voice Outbound (API)" et "OutboundCall" (obsolète) sont disponibles pour le moment.
agent_email TRUE Chaîne Adresse e-mail de l'agent qui sera affecté à l'appel sortant.
ticket_id FALSE Chaîne l'ID de la demande CRM, et le système appellera l'utilisateur final associé à la demande.
end_user_number FALSE Chaîne Numéro de téléphone de l'utilisateur final qui composera le numéro. ticket_id est prioritaire par rapport à end_user_number.
outbound_number FALSE Chaîne Numéro sortant correctement formé, géré depuis Paramètres > Numéros de téléphone > Gestion des numéros de téléphone. Le numéro sortant par défaut sera utilisé si ce champ est vide
lang FALSE Chaîne Langue de l'appel. Utilise les codes ISO 639-1. (Par défaut : "en")

Point de terminaison :

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

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

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

Exemples de requêtes et de réponses

Les sections suivantes fournissent des exemples de requêtes envoyées au point de terminaison.

Erreur : ID de la demande ou numéro de l'utilisateur final requis

Dans cet exemple, le scénario d'échec de l'ID de ticket ou du numéro de l'utilisateur final est manquant, mais obligatoire.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

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

Réponse : Erreur : ticket_id ou end_user_number requis

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

Code d'état : 400

Erreur : Veuillez indiquer l'adresse e-mail de l'agent

Dans cet exemple, nous montrons le scénario d'échec dans lequel l'adresse e-mail de l'agent n'est pas fournie, mais est requise.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Outbound (API)",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
Réponse : Erreur : Adresse e-mail de l'agent requise
{
    "message": "Agent email required"
}

Code d'état : 400

Créer un appel sortant avec le numéro de l'utilisateur final

Dans cet exemple, nous montrons comment créer un appel sortant en fournissant le numéro de l'utilisateur final.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "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"
}
Réponse : Créez un appel sortant avec 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"
}

Code d'état : 201

Erreur : Type d'appel non valide

Dans cet exemple, nous présentons le scénario d'échec dans lequel le type d'appel fourni n'est pas valide.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "ScheduledCall",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
Réponse : Erreur : Type d'appel non valide
{
    "message": "Invalid call type"
}

Code d'état : 400

Demander à l'adaptateur d'appel d'utiliser plusieurs numéros sortants

Dans cet exemple, nous montrons comment interroger l'adaptateur d'appel avec plusieurs numéros de téléphone sortants.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

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

Code d'état : 202

Accepté : l'agent doit passer un appel sortant avec l'ID de la demande

Dans cet exemple, nous montrons comment passer un appel sortant avec un ID de ticket et l'agent accepte la requête.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json
***Corps :*** ```json { "call_type": "Voice Outbound (API)", "agent_email": "allen@somedomain.com", "end_user_number": "+1 205-123-4567", "lang": "en" } ``` ***Code d'état :*** 202 #### Erreur : L'agent n'est pas autorisé à passer des appels Dans cet exemple, nous présentons le scénario d'échec dans lequel une requête de création d'appel est envoyée, mais l'agent n'est pas autorisé à passer des appels sortants. ##### Requête ***En-têtes :***
Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
Réponse : Erreur : l'agent n'est pas autorisé à passer des appels
{
    "message": "Agent does not have access to make calls"
}

Code d'état : 400

Créez un appel sortant avec l'ID de la demande.

Dans cet exemple, nous présentons le scénario de création d'un appel sortant avec un ID de ticket.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "ticket_id": "71450",
    "outbound_number": "+1 339-219-5276",
    "lang": "en"
}
Réponse : Créer un appel sortant avec 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"
}

Code d'état : 201

Accepté : vous devez choisir un numéro pour les appels sortants

Dans cet exemple, nous présentons le scénario dans lequel une demande d'appel sortant est créée avec la nécessité de choisir un numéro sortant, puis est acceptée.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

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

Code d'état : 202

Erreur : l'agent n'est pas disponible pour prendre cet appel

Dans cet exemple, nous présentons le scénario d'échec dans lequel un appel est créé, mais l'agent n'est pas disponible pour l'accepter.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
Réponse : Erreur : l'agent n'est pas disponible pour prendre cet appel
{
    "message": "Agent is not available to take this call"
}

Code d'état : 400

Erreur : le numéro de l'utilisateur final n'est pas correctement mis en forme

Dans cet exemple, nous présentons le scénario d'échec dans lequel le numéro de téléphone de l'utilisateur final fourni est incorrect.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
Réponse : Erreur : end_user_number n'est pas correctement formé
{
    "message": "end_user_number is not well-formed"
}

Code d'état : 400

Erreur : Adresse e-mail de l'agent non valide

Dans cet exemple, nous présentons le scénario d'échec dans lequel l'adresse e-mail de l'agent fournie n'est pas valide.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
Réponse : Erreur : l'adresse e-mail de l'agent n'est pas valide
{
    "message": "Not a valid agent email"
}

Code d'état : 400

Erreur : Contact introuvable

Dans cet exemple, nous présentons le scénario d'échec dans lequel le contact fourni n'a pas pu être localisé.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "ticket_id": 1,
    "lang": "en"
}
Réponse : Erreur : Contact introuvable
{
    "message": "Contact not found"
}

Code d'état : 400

Appel entrant

Paramètre Obligatoire Type de données Définition
call_type TRUE Chaîne Type d'appel à créer. Utilisez "Voice Inbound (API)" ou "IncomingCall" (obsolète) pour créer un appel entrant.
menu_id TRUE Integer ID du menu auquel attribuer l'appel. Seuls les ID de menu Web et de réponse vocale interactive sont acceptés.
end_user_number TRUE Chaîne Numéro de téléphone de l'utilisateur final qui sera composé. Si un ticket_id et un end_user_number sont tous deux transmis, le ticket_id est prioritaire.
lang FALSE Chaîne Langue de l'appel. Utilise les codes ISO 639-1. (Par défaut : "en")
ticket_id FALSE Chaîne ID de la demande CRM. Le numéro de téléphone de l'utilisateur final associé au ticket sera composé. Si un ticket_id et un end_user_number sont tous deux transmis, le ticket_id est prioritaire.
outbound_number FALSE Chaîne Numéro de téléphone sortant à utiliser pour l'appel. Le numéro de téléphone sortant global par défaut sera utilisé si l'entrée n'est pas transmise ou n'est pas valide. Les numéros sortants sont gérés depuis Paramètres > File d'attente > MODIFIER / AFFICHER > Sélectionner une file d'attente > Numéros de téléphone sortants.
recording_permission FALSE Chaîne La valeur n'est évaluée que si la fonctionnalité "Options d'enregistrement des appels" est définie sur "Demander à l'utilisateur l'autorisation d'enregistrer". Configurable dans Paramètres > File d'attente > MODIFIER / AFFICHER > Sélectionner une file d'attente > Options d'enregistrement des appels. Si la valeur est "recording_permission_not_asked" (par défaut) ou "recording_permission_denied", l'appel ne sera pas enregistré. Si la valeur est "recording_permission_granted", l'appel sera enregistré.

Point de terminaison :

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

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "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"
}

Exemples de requêtes et de réponses

Les sections suivantes fournissent des exemples de requêtes envoyées au point de terminaison.

Erreur : le numéro de l'utilisateur final n'est pas correctement formaté

Dans cet exemple, nous présentons le scénario d'échec dans lequel un appel entrant est créé, mais le numéro d'utilisateur final fourni est incorrect.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 999-657-12",
    "recording_permission": "recording_permission_granted"
}
Réponse : Erreur : end_user_number n'est pas correctement formaté
{
    "message": "end_user_number is not well formed"
}

Code d'état : 400

Erreur : Le menu est à l'état "redirection manuelle", impossible d'accepter les appels

Dans cet exemple, nous présentons le scénario d'échec dans lequel un appel est acheminé vers un ID de menu, mais le menu est en état de redirection manuelle et ne peut donc pas recevoir d'appels entrants.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Réponse : Erreur : Le menu est en état de "redirection manuelle", impossible d'accepter les appels
{
    "message": "Menu is in 'manual redirection' state, can't accept calls"
}

Code d'état : 400

Erreur : Type d'appel non valide

Dans cet exemple, nous montrons le scénario d'échec dans lequel un appel entrant est créé, mais le type d'appel fourni n'est pas valide.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "InvalidCallType",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Réponse : Erreur : Type d'appel non valide
{
    "message": "Invalid call type"
}

Code d'état : 400

Erreur : Veuillez indiquer un ID de menu

Dans cet exemple, nous présentons le scénario d'échec dans lequel un appel entrant est créé, mais l'ID de menu fourni n'est pas valide.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Réponse : Erreur : menu_id est obligatoire
{
    "message": "menu_id is required"
}

Code d'état : 400

Erreur : Seuls les ID de menu mobile et de réponse vocale interactive sont autorisés

Dans cet exemple, nous présentons le scénario d'échec dans lequel un appel entrant est créé, mais l'ID de menu fourni n'est pas un ID de menu de SVI ou de menu mobile.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 50,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Réponse : Erreur : seuls les ID de menu de réponse vocale interactive et de menu mobile sont autorisés
{
    "message": "Only IVR and mobile menu IDs are permitted"
}

Code d'état : 400

Créer un appel entrant avec le numéro de l'utilisateur final

Cet exemple montre comment créer un appel entrant avec un numéro d'utilisateur final spécifique.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+82-10-6861-2345",
    "recording_permission": "recording_permission_granted"
}
Réponse : Créer un appel entrant avec 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"
}

Code d'état : 201

Erreur : Le menu est en mode "En dehors des horaires d'ouverture" et ne peut pas accepter les appels entrants

Cet exemple illustre l'échec lorsque l'ID de menu fourni est en dehors des horaires d'ouverture.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Réponse : Erreur : Le menu est en mode "En dehors des horaires d'ouverture" et ne peut pas accepter les appels entrants
{
    "message": "Menu is in 'after hours' state, can't accept incoming calls"
}

Code d'état : 400

Erreur : Langue non disponible

Cet exemple illustre la requête d'échec lorsque la langue spécifiée n'est pas disponible.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Inbound (API)",
    "lang": "fr",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Réponse : Erreur : la langue n'est pas disponible
{
    "message": "Language 'fr' is not available"
}

Code d'état : 400

Créer un appel entrant avec un ID de demande

Cet exemple illustre la requête permettant de créer un appel entrant avec un ID de ticket associé.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "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"
}
Réponse : Créer un appel entrant avec 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"
}

Code d'état : 201

Erreur : Langue introuvable

Cet exemple illustre l'échec lorsque la langue fournie est introuvable.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Inbound (API)",
    "lang": "xy",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Réponse : Erreur : Langue introuvable
{
    "message": "Language 'xy' is not found"
}

Code d'état : 400

Erreur : menu_id introuvable

Cet exemple illustre l'échec lorsque l'ID de menu fourni est introuvable.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9999,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Réponse : Erreur : menu_id introuvable
{
    "message": "menu_id 9999 is not found"
}

Code d'état : 400

Erreur : menu_id n'est pas au bon format

Cet exemple illustre l'échec lorsque l'ID de menu fourni n'est pas correct.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": "menu_999",
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Réponse : Erreur : menu_id n'est pas au bon format
{
    "message": "menu_id is not well formed"
}

Code d'état : 400

Erreur : Vous devez indiquer un numéro d'utilisateur final

Dans cet exemple, nous montrons le scénario d'échec dans lequel un appel entrant est créé, mais le numéro de téléphone de l'utilisateur final n'a pas été fourni.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "recording_permission": "recording_permission_granted"
}
Réponse : Erreur : end_user_number est obligatoire
{
    "message": "end_user_number is required"
}

Code d'état : 400

Appel planifié

Paramètre Obligatoire Type de données Définition
call_type TRUE Chaîne Type d'appel à créer. Utilisez "Voice Scheduled (API)" ou "ScheduledCall" (obsolète) pour créer un appel planifié.
menu_id TRUE Integer ID du menu auquel attribuer l'appel. Seuls les ID de menu pour mobile et Web sont acceptés.
call_id FALSE Integer ID de l'appel précédent, qui sera associé en tant qu'appel parent de l'appel planifié nouvellement créé. Lorsque l'ID d'appel est utilisé, menu_id peut être facultatif.
end_user_number TRUE Chaîne Numéro de téléphone de l'utilisateur final qui sera composé. Si un ticket_id et un end_user_number sont tous deux transmis, le ticket_id est prioritaire.
lang FALSE Chaîne Langue de l'appel. Utilise les codes ISO 639-1. (Par défaut : "en")
ticket_id FALSE Chaîne ID de la demande CRM. Le numéro de téléphone de l'utilisateur final associé au ticket sera composé. Si un ticket_id et un end_user_number sont tous deux transmis, le ticket_id est prioritaire.
scheduled_at TRUE Chaîne Heure programmée de l'appel. Utilisez le format ISO 8601 pour indiquer une date et une heure futures valides.
recording_permission FALSE Chaîne La valeur n'est évaluée que si la fonctionnalité "Options d'enregistrement des appels" est définie sur "Demander à l'utilisateur l'autorisation d'enregistrer". Configurable dans Paramètres > File d'attente > MODIFIER / AFFICHER > Sélectionner une file d'attente > Options d'enregistrement des appels. Si la valeur est "recording_permission_not_asked" (par défaut) ou "recording_permission_denied", l'appel ne sera pas enregistré. Si la valeur est "recording_permission_granted", l'appel sera enregistré.

Point de terminaison :

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

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "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"
}

Exemples de requêtes et de réponses

Les sections suivantes fournissent des exemples de requêtes envoyées au point de terminaison.

Erreur : end_user_number n'est pas correctement formé

Cet exemple illustre l'échec dû au format incorrect de end_user_namber.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "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"
}
Réponse : Erreur : end_user_number n'est pas correctement formaté
{
    "message": "end_user_number is not well formed"
}

Code d'état : 400

Erreur : Le menu est à l'état "redirection manuelle", impossible d'accepter les appels

Cet exemple illustre l'échec lorsque l'ID de menu spécifié est défini sur la redirection de menu et ne peut pas accepter d'appels.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "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"
}
Réponse : Erreur : Le menu est en état de "redirection manuelle", impossible d'accepter les appels
{
    "message": "Menu is in 'manual redirection' state, can't accept calls"
}

Code d'état : 400

Erreur : Type d'appel non valide

Cet exemple illustre l'échec d'une requête lorsque le type d'appel n'est pas valide.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "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"
}
Réponse : Erreur : Type d'appel non valide
{
    "message": "Invalid call type"
}

Code d'état : 400

Erreur : menu_id est obligatoire

Cet exemple illustre la requête et la réponse lorsqu'un ID de menu n'est pas fourni, mais qu'il est obligatoire.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "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"
}
Réponse : Erreur : menu_id est obligatoire
{
    "message": "menu_id is required"
}

Code d'état : 400

Erreur : Seuls les ID de menu mobile et Web sont autorisés

Cet exemple illustre une requête qui échoue lorsqu'un ID de menu fourni n'est pas un ID de menu Web ou mobile.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "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"
}
Réponse : Erreur : Seuls les ID de menu mobile et Web sont autorisés
{
    "message": "Only mobile and web menu IDs are permitted"
}

Code d'état : 400

Créer un appel programmé avec l'ID du menu

Cet exemple montre comment créer un appel planifié avec un ID de menu spécifique.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "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"
}
Réponse : Créer un appel programmé avec l'ID du 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"
}

Code d'état : 201

Créer un appel programmé avec l'ID d'appel

Cet exemple montre comment créer un appel programmé avec un ID d'appel spécifique.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "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"
}
Réponse : Créer un appel programmé avec un ID d'appel
{
    "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"
}

Code d'état : 201

Erreur : Le menu est en mode "En dehors des horaires d'ouverture" et ne peut pas accepter les appels entrants

Dans cet exemple, nous présentons le scénario d'échec dans lequel un appel planifié est créé, mais le menu fourni est en dehors des heures d'ouverture et ne peut donc pas recevoir d'appels entrants.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "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"
}
Réponse : Erreur : Le menu est en mode "En dehors des horaires d'ouverture" et ne peut pas accepter les appels entrants
{
    "message": "Menu is in 'after hours' state, can't accept incoming calls"
}

Code d'état : 400

Erreur : Langue non disponible

Cet exemple illustre l'échec lorsque la langue spécifiée n'est pas valide.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "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"
}
Réponse : Erreur : la langue n'est pas disponible
{
    "message": "Language 'fr' is not available"
}

Code d'état : 400

Erreur : Langue introuvable

Dans cet exemple, nous présentons le scénario d'échec dans lequel un appel planifié est créé, mais la langue n'est pas valide ou n'est pas disponible.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "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"
}
Réponse : Erreur : Langue introuvable
{
    "message": "Language 'xy' is not found"
}

Code d'état : 400

Erreur : ID de menu introuvable

Dans cet exemple, nous présentons le scénario d'échec dans lequel un appel planifié est créé, mais l'ID de menu fourni n'est pas valide et est introuvable.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "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"
}
Réponse : Erreur : ID de menu introuvable
{
    "message": "menu_id 9999 is not found"
}

Code d'état : 400

Erreur : l'ID du menu n'est pas au bon format

Dans cet exemple, nous présentons le scénario d'échec dans lequel un appel planifié est créé, mais l'ID de menu fourni est incorrect.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "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"
}
Réponse : Erreur : menu_id n'est pas au bon format
{
    "message": "menu_id is not well formed"
}

Code d'état : 400

Erreur : Vous devez indiquer un numéro d'utilisateur final

Dans cet exemple, nous présentons le scénario d'échec dans lequel un appel planifié est créé, mais le numéro de l'utilisateur final n'a pas été fourni.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Réponse : Erreur : end_user_number est obligatoire
{
    "message": "end_user_number is required"
}

Code d'état : 400

Erreur : scheduled_at est obligatoire

Dans cet exemple, nous présentons le scénario d'échec dans lequel un appel planifié est créé, mais la valeur "scheduled_at" est manquante alors qu'elle est requise.

Requête

En-têtes :

Clé Valeur Description
Content-Type application/json

Corps :

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Réponse : Erreur : scheduled_at est obligatoire
{
    "message": "scheduled_at is required"
}

Code d'état : 400

Obtenir des attributs de données réservés lors d'un appel

Point de terminaison

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

Exemples de requêtes et de réponses

Cette section contient un exemple de requête et de réponse pour le point de terminaison.

Opération réussie

Cet exemple montre un appel réussi.

Requête

Variables d'URL

Clé Valeur Description
id entier (obligatoire)
Réponse
{
    "verified_customer": "boolean",
    "bad_actor": "boolean",
    "repeat_customer": "boolean"
}

Code d'état 0

Mettre à jour les attributs de données réservés pendant un appel

Point de terminaison

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

Variables d'URL

Clé Valeur Description
id entier (obligatoire)

Body

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

Transmettre des paramètres de données aux agents virtuels en cours de session

Pour utiliser l'API Apps afin de transmettre des paramètres de données aux agents virtuels au milieu d'une session d'appel, consultez Transmettre des paramètres de données aux agents virtuels en cours de session.