API gestion des appels sortants et campagnes

Guide / Voice Management / Module - Voice Management

API gestion des appels sortants et campagnes

Cette API permet de gérer les appels à effectuer, soit en appels sortants unitaires, soit sous forme de campagne d’appels sortants.

L’API permet ainsi de :

  1. Demander un nouvel appel sortant
  2. Consulter l’état d’un appel sortant
  3. Consulter l’état d’un appel sortant

L’API fonctionne suivante un paradigme de type REST, en acceptant des données sous forme de paramètres passés en GET ou en POST, et retourne des données au format JSON.

1.1 Paramètres

Toutes les fonctions d’API nécessitent l’usage des paramètres suivants (en plus des paramètres spécifiques) :

NomTypeDéfautOblig.Description
auth_idAlphanum 32OIdentifiant utilisateur API
auth_passwordAlphanum 32OMot de passe

1.2 Retour

En cas de succès, l’API répond 200 OK ainsi que les champs spécifiques à la fonction appelée.

En cas d’erreur, un code retour HTTP approprié est utilisé et le message JSON contiendra les champs suivants :

NomTypeDescription
statusNumCode de retour HTTP
err_codeAlphanum 16OK en cas de succès, ou un code d’erreur spécifique, par exemple INVALID_AUTH
err_msgAlphanumMessage d’erreur (lisible par un humain)

L’usage des campagnes est optionnel : il permet d’avoir un suivi et une visualisation d’un ensemble d’appels à effectuer.

L’API propose les fonctions suivantes :

  1. Créer une nouvelle campagne
  2. Modifier une campagne
  3. Consulter l’état d’une campagne (statistiques)

2.1 Créer une nouvelle campagne

URL/vm/campaign
Méthode(s)POST

Paramètres

NomTypeDéfautOblig.Description
nameAlphanum 32 ONom de la campagne à créer
recordBool0NActivation de l’enregistrement de tous les appels pour cette campagne. NB: même si cette valeur est à 0, l’enregistrement peut être actif pour d’autres raisons (par exemple, configuré sur un agent)

Retour

NomTypeDescription
id_campaignNumIdentifiant de la nouvelle campagne, à utiliser pour d’autres appels d’API

2.2 Modifier une campagne

URL/vm/campaign/<id_campaign>
Méthode(s)POST

Paramètres

NomTypeDéfautOblig.Description
nameAlphanum 32 NNouveau nom de la campagne
recordBool0NActivation de l’enregistrement de tous les appels pour cette campagne. NB: même si cette valeur est à 0, l’enregistrement peut être actif pour d’autres raisons (par exemple, configuré sur un agent)
pauseBool NDés/activation de la mise en pause de la campagne (inchangé si paramètre absent)

Retour

NomTypeDescription
id_campaignNumIdentifiant de la campagne
nameAlphanum 32Nom de la campagne
pauseBoolIndication de pause de la campagne
recordBoolIndication de l’enregistrement activé

2.3 Annuler une campagne

URL/vm/campaign/<id_campaign>/cancel
Méthode(s)POST

Paramètres

Aucun

Retour

NomTypeDescription
id_campaignNumIdentifiant de la campagne
nameAlphanum 32Nom de la campagne
pauseBoolIndication de pause de la campagne
recordBoolIndication de l’enregistrement activé

2.4 Consulter l’état d’une campagne

URL/vm/campaign/<id_campaign>
Méthode(s)GET

Paramètres

Aucun

Retour

NomTypeDescription
id_campaignNumIdentifiant de la campagne
nameAlphanum 32Nom de la campagne
pauseBoolIndication de pause de la campagne
recordBoolIndication de l’enregistrement activé
total_calls_countNum 8Nombre total d’appels à passer
ok_status_countNum 8Nombre d’appels réussis
ko_status_countNum 8Nombre d’appels en échec
pending_status_countNum 8Nombre d’appels encore à effectuer
 

3.1 Demander un nouvel appel sortant

URL/vm/outbound_call
Méthode(s)POST

Format des requêtes

Les requêtes devront se faire sous la forme

curl -u <username>:<password> "https://api.axialys.com/vm/outbound_call" -X POST -d '{"dest_number":<numéro>,"id_agent":<id_agent>}'

Paramètres

NomTypeDéfautOblig.Description
id_campaignNumNIdentifiant de la campagne de laquelle l’appel fait partie
typeAUTO/MANUALMANUALNType pour passer l’appel sortant. AUTO : l’appel est automatiquement lancé dès qu’un agent est libre, MANUAL l’agent doit valider le lancement de l’appel
id_agentNum 10 O/NL’agent qui va devoir faire l’appel (obligatoire si un groupe n’est pas choisi)
id_groupNum 10 O/NLe groupe d’agents qui va devoir faire l’appel (obligatoire si un opérateur n’est pas choisi)
dest_numberAlphanum 1024 OUn ou plusieurs numéros de destinataires en fonction de s’il s’agit d’une campagne ou d’un appel sortant unitaire (sous le format E.164 sans +, séparés par des virgules). Ex: 33170200200,33634123452
priorityNum 3NNPriorité d’appel; par défaut 10; si la valeur est inférieure, alors cet appel sera prioritaire; si elle est supérieure, il sera non prioritaire
variablesAlphanum 255 NVariables spécifiques à l’appel, présentées dans la popup et utulisables pour le suivi statistiques. Format de type structure JSON. Ex: {“nom_valeur1”:“valeur1”,“nom_valeur2”:“valeur2”}
ring_timeoutNum 430NTemps max de sonnerie, en seconde
retriesNum 43NNombre maximum de tentative de rappel en cas d’échec
retry_timeoutNum 4300NTemps (minimal) entre chaque nouvelle tentative, en secondes
auto_timeoutNum 40NTemps (minimal) avant le déclenchement automatique de l’appel, en secondes
unassign_timeoutNum 460NTemps maximum qu’a l’opérateur pour passer l’appel avant attribution à un autre opérateur, en secondes
start_from_dateDate/HeureMaintenantNDate de début pour passer un ou plusieurs appels, sous forme ISO8601. Ex: 2016-11-05T09:00
end_before_dateDate/HeureAucunNDate de fin pour passer un ou plusieurs appels, sous forme ISO8601
start_from_hourHeure NHeure (quotidienne) de début pour passer un ou plusieurs appels, sous forme ISO8601 ou HH:MM:SS
end_before_hourHeure NHeure (quotidienne) de fin pour passer un ou plusieurs appels, sous forme ISO8601 ou HH:MM:SS
Il est possible d’assigner des appels sortants à un agent d’un groupe si “id_agent” et “id_group” sont renseignés dans la même requête.

Retour

NomTypeDescription
id_out_callNumUn à plusieurs identifiants de numéros de destinataires en fonction de s’il s’agit d’une campagne ou d’un appel sortant unitaire, séparés par des virgules

3.2 Consulter l’état d’un appel sortant

URL/vm/outbound_call/<id_out_call>
Méthode(s)GET

Paramètres

Aucun

Retour

Les champs identiques à ceux passés lors de la création de l’appel sont retournés, avec en plus :

NomTypeDescription
date_submittedDate/HeureDate de création, sous forme ISO8601
alloc_to_id_agentNumIdentifiant de l’agent ayant passé l’appel
statusPENDING/ASSIGNED/DIALING/CONNECTED/SUCCESS/FAILUREStatut de l’appel
call_dateDate/HeureDate de l’appel passé (ou de la dernière tentative), sous forme ISO8601
answered_durationNumDurée de l’appel (en secondes)
failure_reasonAlphanum 16Raison de l’échec

3.3 Supprimer un ou des appels sortants

URL/vm/outbound_call
Méthode(s)DELETE
Seul les demandes dans l’état PENDING sont impactées par cette méthode

Format des requêtes

Les requêtes devront se faire sous la forme

curl -u <username>:<password> "https://api.axialys.com/vm/outbound_call" -X DELETE -d '{"dest_number":<numéro>,"id_agent":<id_agent>}'

Paramètres

NomTypeDéfautOblig.Description
id_campaignNumNIdentifiant de la campagne de laquelle l’appel fait partie
typeAUTO/MANUALMANUALNType pour passer l’appel sortant. AUTO : l’appel est automatiquement lancé dès qu’un agent est libre, MANUAL l’agent doit valider le lancement de l’appel
dest_numberAlphanum 1024 OUn ou plusieurs numéros de destinataires en fonction de s’il s’agit d’une campagne ou d’un appel sortant unitaire (sous le format E.164 sans +, séparés par des virgules). Ex: 33170200200,33634123452
priorityNum 3NNPriorité d’appel; par défaut 10; si la valeur est inférieure, alors cet appel sera prioritaire; si elle est supérieure, il sera non prioritaire
variablesAlphanum 255 NVariables spécifiques à l’appel, présentées dans la popup et utulisables pour le suivi statistiques. Format de type structure JSON. Ex: {“nom_valeur1”:“valeur1”,“nom_valeur2”:“valeur2”}
ring_timeoutNum 430NTemps max de sonnerie, en seconde
retriesNum 43NNombre maximum de tentative de rappel en cas d’échec
retry_timeoutNum 4300NTemps (minimal) entre chaque nouvelle tentative, en secondes
auto_timeoutNum 40NTemps (minimal) avant le déclenchement automatique de l’appel, en secondes
unassign_timeoutNum 460NTemps maximum qu’a l’opérateur pour passer l’appel avant attribution à un autre opérateur, en secondes
start_from_dateDate/HeureMaintenantNDate de début pour passer un ou plusieurs appels, sous forme ISO8601. Ex: 2016-11-05T09:00
end_before_dateDate/HeureAucunNDate de fin pour passer un ou plusieurs appels, sous forme ISO8601
start_from_hourHeure NHeure (quotidienne) de début pour passer un ou plusieurs appels, sous forme ISO8601 ou HH:MM:SS
end_before_hourHeure NHeure (quotidienne) de fin pour passer un ou plusieurs appels, sous forme ISO8601 ou HH:MM:SS
id_agentNum 10 NL’agent qui va devoir faire l’appel (obligatoire si un groupe n’est pas choisi)
id_groupNum 10 NLe groupe d’agents qui va devoir faire l’appel (obligatoire si un opérateur n’est pas choisi)

Retour

Nombre d’appels impactés.