Centre d'aide Aircall | Widgets Smartflows : Ring to (via API) documentation technique

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 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 outils d’assistance.

Important: :
Le widget Ring to (via API) est disponible uniquement sur le plan Professionnel. Pour passer à ce plan, 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 souhaitez récupérer les données. Les méthodes prises en charge incluent :

Authentification basique
Jeton Bearer
Clé API
OAuth

Exemple (API Aircall) :

Accédez à Intégrations & API > Clés API dans le tableau de bord 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), allez dans Identifiants et définissez :
- Nom d’utilisateur = ID de clé API
- Mot de passe = jeton API

En savoir plus sur la localisation de votre clé API Aircall dans notre article Où trouver ma clé API Aircall.

Connaissance de l’API de la plateforme

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

Bien que Où trouver ma clé API Aircall utilise l’API Aircall comme exemple, vous pouvez aussi 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 les APIs. Vous devez être familiarisé avec 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 Services Professionnels d’Aircall peut fournir du conseil et un support à l’implémentation.

Considérations d’utilisation

Le widget Ring to (via API) permet un routage d’appel dynamique (« intelligent ») basé sur des données externes. Il peut interroger tout système supportant les APIs 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 point de terminaison répond dans ce délai, sinon le widget pourrait ne pas être en mesure de récupérer la cible de routage.

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

Type de réponse	Description
Utilisateur	Routage vers un agent spécifique en utilisant son ID utilisateur Aircall ou son email.
Équipe	Routage vers une équipe Aircall spécifique en utilisant son ID d’équipe.
Numéro Aircall	Routage interne vers un autre numéro Aircall en utilisant son ID de numéro.
Numéro externe	Routage 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 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 (utilisateur, équipe, numéro ou externe)
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, équipe, interne et externe.

Si la cible résolue est une équipe, les règles d’appel standard s’appliquent. Si c’est un utilisateur ou un numéro, ces règles ne s’appliquent pas.

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

Étapes de configuration

Le widget détermine s’il faut sonner vers un Utilisateur, une Équipe, un Numéro Aircall, un Numéro externe, ou une Cible dynamique (ID) selon 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 API que vous souhaitez utiliser.
- Exemple : Lors de l’utilisation du point de terminaison 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 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 email)
É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 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 équipe, les règles de sonnerie seront appliquées en conséquence.

Test de la configuration

Utilisez le champ Test de réponse pour simuler des requêtes API et confirmer que vos chemins configurés retournent les bonnes valeurs.

Exemple d’entrée de test :

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

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

En cas d’erreur, consultez la section Erreurs dans la documentation de l’API Aircall pour 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 Vue d’ensemble du routage Smartflows.

CONSEIL :
Si vous avez besoin d’aide pour configurer ou tester votre intégration API, l’équipe Services Professionnels d’Aircall peut vous assister dans l’implémentation pratique et le dépannage.

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 outils d’assistance.

Important: :
Le widget Ring to (via API) est disponible uniquement sur le plan Professionnel. Pour passer à ce plan, 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 souhaitez récupérer les données. Les méthodes prises en charge incluent :

Authentification basique
Jeton Bearer
Clé API
OAuth

Exemple (API Aircall) :

Accédez à Intégrations & API > Clés API dans le tableau de bord 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), allez dans Identifiants et définissez :
- Nom d’utilisateur = ID de clé API
- Mot de passe = jeton API

En savoir plus sur la localisation de votre clé API Aircall dans notre article Où trouver ma clé API Aircall.

Connaissance de l’API de la plateforme

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

Connaissance du JSON

CONSEIL :
Si vous avez besoin d’aide pour configurer le widget, l’équipe Services Professionnels d’Aircall peut fournir du conseil et un support à l’implémentation.

Considérations d’utilisation

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

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

Type de réponse	Description
Utilisateur	Routage vers un agent spécifique en utilisant son ID utilisateur Aircall ou son email.
Équipe	Routage vers une équipe Aircall spécifique en utilisant son ID d’équipe.
Numéro Aircall	Routage interne vers un autre numéro Aircall en utilisant son ID de numéro.
Numéro externe	Routage 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 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 (utilisateur, équipe, numéro ou externe)
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, équipe, interne et externe.

Si la cible résolue est une équipe, les règles d’appel standard s’appliquent. Si c’est un utilisateur ou un numéro, ces règles ne s’appliquent pas.

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

Étapes de configuration

Le widget détermine s’il faut sonner vers un Utilisateur, une Équipe, un Numéro Aircall, un Numéro externe, ou une Cible dynamique (ID) selon 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 API que vous souhaitez utiliser.
- Exemple : Lors de l’utilisation du point de terminaison 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 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 email)
É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 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 équipe, les règles de sonnerie seront appliquées en conséquence.

Test de la configuration

Utilisez le champ Test de réponse pour simuler des requêtes API et confirmer que vos chemins configurés retournent les bonnes valeurs.

Exemple d’entrée de test :

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

En cas d’erreur, consultez la section Erreurs dans la documentation de l’API Aircall pour des conseils de dépannage.

Paramètres de sonnerie

Pour plus de détails, consultez notre article du Centre d’aide Vue d’ensemble du routage Smartflows.

CONSEIL :
Si vous avez besoin d’aide pour configurer ou tester votre intégration API, l’équipe Services Professionnels d’Aircall peut vous assister dans l’implémentation pratique et le dépannage.