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

Le widget Smart Routing: 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 de 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, veuillez contacter votre gestionnaire 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) :

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

Pour en savoir plus sur la manière 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 du JSON

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

CONSEIL:
Si vous avez besoin d’aide pour configurer le widget, notre équipe technique peut fournir un accompagnement de conseil et de mise en œuvre. Veuillez contacter notre équipe Account Management.

Considérations d’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) expireront 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 :

Type de réponse	Description
Utilisateur	Achemine vers un agent spécifique à l’aide de son ID utilisateur Aircall ou de son e-mail.
Équipe	Achemine vers une équipe Aircall spécifique à l’aide de son ID d’équipe.
Numéro Aircall	Achemine en interne vers un autre numéro Aircall à l’aide de son ID de numéro.
Numéro externe	Achemine en externe vers un numéro de téléphone (doit être au format international E.164).
Cible dynamique (ID)	Permet à votre API externe de spécifier dynamiquement à la fois le type de cible et l’ID de la cible.

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 Dynamic Target, 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. Si c’est un utilisateur ou 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 :

Dans l’éditeur Smartflows, ajoutez un widget Ring to (via API).
Choisissez la méthode HTTP (GET ou POST), selon la section de l’API que vous souhaitez utiliser.
- Exemple : lors de l’utilisation de l’endpoint Search Calls de l’API Aircall, sélectionnez GET.
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.
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 utilisateur.

Exemple de réponse JSON Dynamic Target :

{
  "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 vos chemins configurés renvoient les valeurs correctes.

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 lancez le test, le widget remplace ces variables et affiche les résultats analysés.

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

Paramètres de sonnerie

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

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

CONSEIL:
Si vous souhaitez exploiter cette fonctionnalité mais 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 de mise en œuvre.