Widgets Smartflows : documentation technique de Ring to (via API)

Le widget routage intelligent : Ring to (via API) utilise une réponse API pour déterminer vers quel utilisateur Aircall, équipe, numéro interne ou numéro externe acheminer un appel, en fonction des données stockées en dehors d’Aircall.

Ce widget offre des capacités de routage dynamique puissantes et flexibles en connectant Aircall à des systèmes tiers tels que des CRM ou des Helpdesk.

Important: Le widget Ring to (via API) est disponible uniquement avec le forfait Professional. Pour effectuer une mise à niveau, contactez votre responsable de compte Aircall.

Prérequis

Avant de configurer le widget, assurez-vous que les exigences suivantes sont remplies.

Identifiants d’authentification

La méthode d’authentification dépend de la plateforme externe dont vous prévoyez de récupérer les données. Les méthodes prises en charge incluent :

• Authentification de base
• Jeton Bearer
• Clé API
• OAuth

Exemple (API Aircall) :

1. Accédez à Integrations & API > API keys dans le tableau de bord Aircall.
2. Générez une nouvelle clé API.
3. Enregistrez à la fois l’ID de la clé API et le jeton.
4. Dans la configuration du widget Ring to (via API), accédez à Identifiants et définissez :
   • Nom d’utilisateur = ID de la clé API
   • Mot de passe = jeton API

Pour en savoir plus sur la façon de trouver votre clé API Aircall, consultez notre article Where to find my Aircall API Key.

Connaissance de l’API de la plateforme

Vous devez comprendre la structure et les endpoints de l’API publique de la plateforme externe.

Bien que Where to find my Aircall API Key utilise l’API Aircall comme exemple, vous pouvez également utiliser des plateformes telles que HubSpot, Salesforce, Zendesk, Intercom, Pipedrive ou des CRM internes.

Connaissance de JSON

Le widget utilise JSON (JavaScript Object Notation) pour échanger des données avec les API. Vous devez connaître les structures JSON de base pour configurer correctement les chemins de données.

Conseil: Si vous avez besoin d’aide pour configurer le widget, l’équipe des services professionnels d’Aircall peut fournir un accompagnement en conseil et en implémentation.

Points à prendre en compte pour l’utilisation

Le widget Ring to (via API) permet un routage d’appels dynamique (« intelligent ») basé sur des données externes. Il peut interroger tout système prenant en charge les API REST et les méthodes d’authentification standard.

Remarque: Les requêtes effectuées par Ring to (via API) expirent après 10 secondes. Assurez-vous que votre endpoint répond dans ce délai, sinon le widget risque de ne pas pouvoir récupérer la cible de routage.

La réponse API doit renvoyer des données dans un format qu’Aircall peut interpréter pour le routage. Les types de réponse pris en charge incluent :

Lors de l’utilisation de Cible dynamique (ID), vous devez définir deux chemins JSON dans le widget :

• Chemin vers le type de cible (user, team, number ou external)
• Chemin vers la valeur cible (l’ID unique de la cible)

Remarque: Pour les réponses Cible dynamique, le widget accepte uniquement les valeurs suivantes pour le type de cible : agent, team, internal et external.

Si la cible résolue est une équipe, les règles de sonnerie standard s’appliquent. S’il s’agit d’un utilisateur ou d’un numéro, ces règles ne s’appliquent pas.

Toute logique avancée (par ex. routage conditionnel, priorisation) doit être traitée dans votre système externe avant de renvoyer la réponse API.

Étapes de configuration

Le widget détermine s’il doit sonner vers un Utilisateur, une Équipe, un Numéro Aircall, un Numéro externe ou une Cible dynamique (ID) en fonction de l’appel API configuré.

Étapes :

1. Dans l’éditeur Smartflows, ajoutez un widget Ring to (via API).
2. Choisissez la méthode HTTP (GET ou POST), selon la section API que vous souhaitez utiliser.
   • Exemple : lors de l’utilisation de l’endpoint Search Calls de l’API Aircall, sélectionnez GET.

3. Saisissez l’URL de l’API, par exemple :

   https://api.aircall.io/v1/calls/search?order=desc&phone_number={{callerNumber}}
   

   Cela recherche les appels les plus récents associés au numéro de téléphone de l’appelant.

4. Utilisez des variables comme callerNumber, targetNumber ou callUUID pour insérer dynamiquement des données spécifiques à l’appel dans votre requête. Consultez la documentation de l’API Aircall pour obtenir la liste complète des paramètres de requête.

Configuration de la réponse

Dans la section Configuration de la réponse, définissez comment la réponse API sera analysée pour déterminer la cible de routage.

Types de réponse pris en charge :

• Utilisateur (ID ou e-mail)
• Équipe (ID)
• Numéro Aircall (interne)
• Numéro externe (format E.164)
• Cible dynamique (ID)

Exemple de chemin JSON :

calls[0].user.id

Ce chemin fait référence au premier élément du tableau « calls » et récupère l’ID de l’utilisateur.

Exemple de réponse JSON Cible dynamique :

{
  "calls": [
    {
      "target_type": "team",
      "target_id": 12345
    }
  ]
}

• Chemin vers le type de cible : calls[0].target_type
• Chemin vers la valeur cible : calls[0].target_id

Si le type de cible est team, les règles de sonnerie seront appliquées en conséquence.

Tester la configuration

Utilisez le champ Test response pour simuler des requêtes API et confirmer que les chemins configurés renvoient les bonnes valeurs.

Exemple d’entrée de test :

{
  "callerNumber": "+15551234567",
  "targetNumber": "+15557654321",
  "callUUID": "abcd-1234-efgh-5678",
  "lineId": 12345
}

Chaque clé du JSON correspond à une variable utilisée dans votre URL ou le corps de votre requête. Lorsque vous exécutez le test, le widget remplacera ces variables et affichera les résultats analysés.

Si une erreur se produit, consultez la section Errors de la documentation de l’API Aircall pour obtenir des conseils de dépannage.

Paramètres de sonnerie

Après avoir configuré et testé votre intégration API, ajustez les Paramètres de sonnerie pour définir comment les appels sont distribués. Ces paramètres fonctionnent de la même manière que ceux du widget Ring to standard.

Pour plus de détails, consultez notre article du centre d’aide Smartflows routing overview.

Conseil: Si cette fonctionnalité vous intéresse mais que vous manquez d’expertise technique, contactez notre équipe Account Management, qui vous mettra en relation avec notre équipe technique pour obtenir de l’aide et des conseils d’implémentation.