Router vos appels avec un web service – Support Ubefone

Déléguez le contrôle de certains appels à un service web externe, pour personnaliser dynamiquement leur traitement. Vous croiserez parfois le nom Smart Routing pour cette fonctionnalité.

Prérequis : un service web capable de recevoir des requêtes HTTP POST en JSON et de répondre en moins de 5 secondes.

L'emplacement de la configuration dépend de l'usage : voir chaque section ci-dessous.

Comment fonctionne l'appel au web service

Ubefone envoie une requête POST à votre service, avec un en-tête Content-Type: application/json.
Votre service doit répondre en moins de 5 secondes, avec un code 2xx. Toute autre réponse, y compris une redirection, est considérée comme un échec.
Ubefone ouvre au maximum 3 connexions simultanées vers votre service. Au-delà, si aucune connexion ne se libère sous 2 secondes, l'appel au web service échoue.
L'authentification HTTP n'est pas prise en charge. Pour sécuriser votre service, utilisez une connexion HTTPS, placez un token dans l'URL, ou autorisez uniquement les adresses IP d'Ubefone (voir Bon à savoir).

Format de la requête envoyée par Ubefone

{
  "svi_input": "132",
  "cti_variables": {},
  "context_variables": {
    "channel_uid": null,
    "caller_number": "+33130303030",
    "called_number": "+33140404040"
  }
}

context_variables contient toujours caller_number et called_number, au format international E164.
cti_variables contient les variables ajoutées par un SVI (si son champ Nom de la variable est renseigné) ou par un web service précédemment appelé.
svi_input n'apparaît que pour la validation d'une saisie de SVI (voir ci-dessous).

Format de la réponse attendue

Votre service doit répondre en JSON, avec une clef response obligatoire (son contenu dépend du service appelé, voir ci-dessous) et une clef additional_cti_variables facultative, pour ajouter des variables réutilisables lors des prochains appels de web service.

Les 3 usages disponibles

Valider une saisie de SVI

Se configure directement dans le SVI concerné : dans le Mode de fonctionnement du SVI, ajoutez un choix dont la destination est un service web (voir Créer un SVI, destinations disponibles).

Utilisez ce web service pour valider ou refuser la saisie d'un appelant dans un SVI. La requête contient svi_input, la valeur saisie par l'appelant.

Répondez { "response": "OK" } pour valider la saisie. Toute autre réponse déclenche la règle d'échec du SVI.

Renvoyer un appel dynamiquement

Se configure comme destination, partout où « service web » apparaît comme option : confirmé dans les renvois exceptionnels (utilisateur, groupe et SVI) et dans les choix de SVI, et probablement ailleurs — chaque sélecteur de destination de renvoi est un candidat.

Utilisable partout où un renvoi d'appel est configurable. La clef response doit être un hash avec :

action : nothing (ne rien faire, l'appel suit son cours normal), drop (raccrocher), voicemail (renvoyer vers le répondeur), ou transfer (transférer l'appel).
destination : uniquement si action vaut transfer — un numéro interne, ou un numéro externe au format E164.

Exemple de réponse transférant l'appel :

{
  "response": {
    "action": "transfer",
    "destination": "+33976677667"
  }
}

Afficher un nom d'appelant (résolution de numéro)

Se configure dans le Selfcare, page Entreprise, bloc Webhooks, champ Web service de résolution de contact.

Ubefone appelle votre service pour les appels entrants externes, afin d'afficher un nom sur les téléphones de vos utilisateurs plutôt que le numéro brut.

Répondez avec une chaîne de caractères pour le nom à afficher ({ "response": "Mr. Dupont" }), ou { "response": null } si aucun nom n'est trouvé. Toute autre réponse est ignorée.

Bon à savoir

Si vous choisissez de sécuriser votre service par une liste blanche d'adresses IP plutôt que par HTTPS ou un token, autorisez les adresses suivantes : 13.36.75.246, 13.36.149.11, 13.36.185.16, 13.37.12.45, 13.37.52.143, 13.37.53.186, 13.37.55.43, 13.37.69.123, 13.37.69.243, 15.188.148.62, 15.188.214.30, 15.236.130.129, 15.236.136.10.
L'identifiant channel_uid fourni dans context_variables n'est pas recommandé pour un usage métier : il sert surtout au diagnostic technique.

Voir aussi