1 CONTROLE DES FLUX DE TELEPHONIE PAR WEB SERVICE
Le serveur de téléphonie peut appeler des web service externes pour déléguer le contrôle des appels.
La configuration des web service est faite dans le Selfcare.
1.1 FONCTIONNEMENT DE L’API
Le serveur de téléphonie se comporte comme un client HTTP.
Le serveur de téléphonie envoie une requête HTTP POST avec un Content-Type application/json.
Le serveur de téléphonie attend une réponse 2xx. Toute autre réponse est considérée comme un échec. Les redirections, en particulier, ne sont pas suivies.
Le serveur de téléphonie utilise des connexions HTTP persistantes.
Le serveur de téléphonie attend une réponse en moins de 5 secondes. Les appels web service bloquent le routage des appels et il est recommandé répondre aussi rapidement que possible.
Le serveur de téléphonie ouvre au plus 3 connexions simultanées. Au-delà de 3 connections, si aucune connexion n’est disponible au-delà de 2 secondes, l’appel à l’API échoue.
L’authentification HTTP n’est pas supportée. Il n’est pas possible d’ajouter de header contenant un token. Pour sécuriser l’API, il est possible :
- D’utiliser une connexion HTTPS
- De mettre le token dans l’URL
- De whitelister les IP en annexe
1.2 FORMAT DES REQUETES
Le corps de la requête est encodé en JSON.
La requête contient un hash avec les clefs suivantes :
- context_variables : hash contenant des informations sur l'appel :
- caller_number : numéro appelant au format E164
- called_number : numéro appelé au format E164
- channel_uid : un identifiant unique de l'appel. L'utilisation de cette variable n’est pas recommandée, son utilisation indique probablement un mauvais design.
- cti_variables : hash contenant les variables cti de l'appel. Ces
variables sont ajoutées à l’appel :- Par un SVI si l’attribut « Nom de la variable » est renseigné dans le Selfcare. Si l’appel passe par plusieurs SVIs, chaque SVI peut stocker le choix ou la saisie de l’utilisateur dans une variable.
- Par un web service service précédemment appelé. (cf. additional_cti_variables)
- Il peut contenir d'autres variables, en fonction du service.
1.3 FORMAT DE LA REPONSE ATTENDUE
Le corps de la réponse doit être encodé en JSON.
La réponse doit être un hash avec les clefs suivantes :
- response : Cette clef est obligatoire. Elle contient le résultat de la commande. Le format dépend du service.
- additional_cti_variables : Cette clef est optionnelle. Elle contient un hash de variables à ajouter aux variables existantes. Ces variables seront communiquées lors des prochains appels web service. Seuls les caractères suivants sont autorisés dans les noms des cti_variables : a-z, A-Z, 0-9, - et _. Les variables ne respectant pas le format sont ignorées.
2 WEB SERVICES EXISTANTS
2.1 VALIDATION DES MENUS
Le web service est appelé pour valider la saisie de l’appelant. Si la saisie est validée, la règle de succès est appliquée. Sinon c’est la règle d’échec qui est appliquée.
2.1.1 REQUETE
La requête POST contient la variable svi_input qui contient la valeur saisie par l'utilisateur.
2.1.2 REPONSE
La clef response doit valoir "OK" afin de valider la saisie. Toute autre réponse est considérée comme un échec.
2.1.3 EXEMPLE
Exemple de corps de requête envoyé par le serveur de téléphonie :
{
"svi_input": "132",
"cti_variables": {},
"context_variables": {
"channel_uid": null,
"caller_number": "+33130303030",
"called_number": "+33140404040"
}
}
Corps de la réponse pour valider la saisie de l’utilisateur :
{
"response": "OK"
}
2.2 RENVOI D'APPEL
Partout où un renvoi d’appel est configurable, le serveur peut appeler un
web service pour renvoyer dynamiquement l’appel
2.2.1 REQUETE
La requête ne contient pas de variable spécifique
2.2.2 REPONSE
La clef response doit être un hash avec les clefs suivantes :
- action. Valeurs possibles :
- nothing : la règle est ignorée, le traitement de l’appel suit son cours. Par exemple si le web service est évalué pour un renvoi immédiat d’utilisateur, l’appel n’est pas renvoyé et le poste de l’utilisateur va sonner. Si par contre le web service est évalué pour un renvoi sur non-réponse d’utilisateur, l’appel n’est pas renvoyé et l’appel est raccroché.
- drop : l’appel est raccroché
- voicemail : renvoi vers répondeur
- transfer : transfert vers un numéro, il faut ajouter une clef destination
- destination : Si l'action est transfer, les valeurs possibles pour la destination sont :
- Un numéro interne
- Un numéro externe au format E164
2.2.3 EXEMPLE
Exemple de corps de requête envoyé par le serveur de téléphonie :
{
"cti_variables": {},
"context_variables": {
"channel_uid": null,
"caller_number": "+33130303030",
"called_number": "+33140404040"
}
}
Exemple de réponse transférant l’appel vers un autre numéro :
{
"response": {
"action": "transfer",
"destination": "+33976677667"
}
}
2.3 RESOLUTION DE NUMERO DE TELEPHONE
La configuration se fait dans le selfcare, au niveau de l’entreprise. Le web service est appelé pour résoudre les numéros de téléphone des appels venant de l’extérieur de façon à afficher un nom sur les téléphones des utilisateurs.
2.3.1 REQUETE
La requête ne contient pas de variable spécifique
2.3.2 REPONSE
La clef response doit contenir :
- Une chaine de caractère contenant le label à afficher
- null en cas d’échec de la résolution
Toute autre réponse est ignorée.
2.3.3 EXEMPLE
Exemple de corps de requête envoyé par le serveur de téléphonie :
{
"cti_variables": {},
"context_variables": {
"channel_uid": null,
"caller_number": "+33130303030",
"called_number": "+33140404040"
}
}
Corps de la réponse pour afficher un label :
{
"response": "Mr. Dupont"
}
Corps de la réponse lorsqu’aucun label n’a été trouvé :
{
"response": null
}
3 ANNEXE
3.1 Adresses IP
Adresses IP de nos serveurs :
- 95.140.12.88/32
- 83.167.153.187/32
- 83.167.153.189/32
- 83.167.153.175/32
- 83.167.143.163/32
- 83.167.153.185/32
- 83.167.143.160/32