Implémentation de référence EspoCRM

Ce document fournit un exemple d'intégration avec une plate-forme CCAI (Contact Center AI Platform) et un CRM personnalisé utilisant EspoCRM. EspoCRM est une application CRM Open Source sans frais qui aide les entreprises à gérer leurs ventes, leur marketing et leur service client grâce à une interface personnalisable. Il propose des fonctionnalités telles que la gestion des contacts, le suivi des activités, l'automatisation des ventes et la gestion des stocks, avec des options d'auto-hébergement ou de déploiement dans le cloud.

Pour configurer votre propre instance EspoCRM, consultez la page Installation d'EspoCRM.

Avant de commencer

Procédez comme suit :

  • Configurez votre pare-feu pour autoriser le trafic provenant de la plate-forme CCAI.

  • Créez un utilisateur d'API dans votre instance EspoCRM, par exemple google_integration_user. Pour en savoir plus, consultez la section API de la documentation EspoCRM.

  • Créez un rôle dans votre instance EspoCRM avec les actions Create (Créer), Read (Lire) et Update (Mettre à jour) qui accèdent aux éléments suivants :

    • Contacts : pour trouver ou créer des appelants
    • Demandes : pour rechercher et enregistrer des tickets

    Pour en savoir plus, consultez la section Gestion des rôles dans la documentation ExpoCRM.

Configurer une connexion d'EspoCRM à CCAI Platform

Pour configurer une connexion entre EspoCRM et CCAI Platform, procédez comme suit :

  1. Dans le portail CCAI Platform, cliquez sur Settings > Developer Settings (Paramètres > Paramètres pour les développeurs). Si le menu Paramètres ne s'affiche pas, cliquez sur Menu.
  2. Pour Agent Platform, sélectionnez Custom CRM.
  3. Cliquez sur le bouton bascule Afficher le CRM dans le portail de la plate-forme CCAI pour l'activer.
  4. Dans le champ URL à afficher, saisissez l'URL à intégrer dans le portail CCAI Platform. Par exemple, https://YOUR_ESPO_DOMAIN/#Case/view/{RECORD_ID}.
  5. Pour Méthode de recherche CRM, sélectionnez API générique.
  6. Pour vous authentifier à l'aide d'un en-tête personnalisé, procédez comme suit :
    1. Dans la section Méthode d'authentification, sélectionnez En-tête personnalisé.
    2. Cliquez sur Ajouter un champ. La boîte de dialogue Ajouter un champ s'affiche.
      1. Dans le champ Clé du champ, saisissez X-Api-Key.
      2. Dans le champ Valeur du champ, saisissez la clé API générée lorsque vous avez créé un utilisateur API dans votre EspoCRM.
      3. Cliquez sur Enregistrer.
  7. Pour définir l'URL de recherche CRM :
    1. Dans la section URL de recherche CRM, dans le champ URL de recherche d'enregistrement, saisissez l'URL permettant de rechercher un enregistrement (par exemple, https://YOUR_ESPO_DOMAIN/#Case/view/{RECORD_ID}).
    2. Dans le champ URL de recherche de compte, saisissez l'URL permettant de rechercher un compte (par exemple, https://YOUR_ESPO_DOMAIN/#Contact/view/{ACCOUNT_ID}).
    3. Cliquez sur Enregistrer. ## Configurer les points de terminaison de l'API

Configurez des points de terminaison compatibles avec EspoCRM pour vous assurer que votre intégration dispose des composants permettant de rechercher des comptes (contacts) et des enregistrements (demandes). Pour en savoir plus sur les variables compatibles, consultez Présentation de l'API dans la documentation EspoCRM.

Configurer les points de terminaison du compte API

Cette section explique comment configurer les points de terminaison des comptes d'API.

Configurer un point de terminaison de requête "Find an account" (Trouver un compte)

Pour configurer le point de terminaison de requête permettant de trouver un compte, procédez comme suit :

  1. Dans la plate-forme CCAI, cliquez sur Settings > Developer Settings (Paramètres > Paramètres pour les développeurs). Si le menu Paramètres ne s'affiche pas, cliquez sur Menu.
  2. Dans le volet CRM, accédez à la section Compte API.
  3. Pour le point de terminaison de requête Find an account, cliquez sur Setup (Configurer). La page Configuration du point de terminaison de l'API générique s'affiche.
  4. Dans le champ URL, saisissez l'URL du compte à rechercher (par exemple, https://YOUR_ESPO_DOMAIN/api/v1/Contact).
  5. Pour Méthode, sélectionnez GET.

  6. Pour configurer les paramètres de requête, procédez comme suit :

    1. Pour configurer le premier paramètre de requête, procédez comme suit :
      1. Cliquez sur Ajouter un champ. La boîte de dialogue Ajouter un champ s'affiche.
      2. Dans le champ Clé du champ, saisissez where[0][attribute].
      3. Dans le champ Valeur du champ, saisissez phoneNumber.
      4. Cliquez sur Enregistrer.

    2. Pour configurer le reste des paramètres de la requête, répétez les étapes précédentes en utilisant les informations du tableau suivant. Vous avez déjà créé le premier paramètre de requête.

      Clé de champ Valeur du champ
      where[0][attribute] phoneNumber
      where[0][type] equals
      where[0][value] {PHONE_NUMBER}
      sortBy createdAt
      asc false

  7. Dans le champ Emplacement des données de réponse, saisissez data.list.

  8. Cliquez sur Enregistrer.

  9. Cliquez sur Back to Developer Settings (Retour aux paramètres du développeur) pour revenir à la page Developer Settings (Paramètres du développeur).

Configurer un point de terminaison "Find an account by ID"

Pour configurer le point de terminaison Find an account by ID (Trouver un compte par ID), procédez comme suit :

  1. Dans le volet CRM, accédez à la section Compte API.
  2. Pour le point de terminaison Find an account by ID (Trouver un compte par ID), cliquez sur Setup (Configurer). La page Configuration du point de terminaison de l'API générique s'affiche.
  3. Dans le champ URL, saisissez l'URL du compte à rechercher (par exemple, https://YOUR_ESPO_DOMAIN/api/v1/Contact/{ACCOUNT_ID}).
    1. Pour Méthode, sélectionnez GET.
  4. Définissez le paramètre Emplacement des données de réponse sur data.
  5. Cliquez sur Enregistrer.
  6. Cliquez sur Revenir aux paramètres du développeur pour revenir à la page Paramètres du développeur.

Configurer un point de terminaison "Créer un compte"

Pour configurer le point de terminaison "Créer un compte", procédez comme suit :

  1. Dans le volet CRM, accédez à la section Compte API.
  2. Pour Créer un point de terminaison de compte, cliquez sur Configurer. La page Configuration du point de terminaison de l'API générique s'affiche.
  3. Dans le champ URL, saisissez l'URL du compte à rechercher (par exemple, https://YOUR_ESPO_DOMAIN/api/v1/Contact).
  4. Pour Méthode, sélectionnez POST.

  5. Pour configurer les paramètres de requête, procédez comme suit :

    1. Pour configurer le premier paramètre de requête, procédez comme suit :
      1. Pour Paramètres de la requête, cliquez sur Ajouter un champ. La boîte de dialogue Ajouter un champ s'affiche.
      2. Dans le champ Clé du champ, saisissez phoneNumber.
      3. Dans le champ Valeur du champ, saisissez {PHONE_NUMBER}.
      4. Cliquez sur Enregistrer.

    2. Pour configurer le reste des paramètres de la requête, répétez l'étape précédente en utilisant les informations du tableau suivant. Vous avez déjà créé le premier paramètre de requête.

      Clé du paramètre Valeur du paramètre
      phoneNumber {PHONE_NUMBER}
      firstName New Caller
      lastName {CALL_ID}
      name New Caller {CALL_ID}

  6. Définissez l'emplacement des données de réponse sur data.

  7. Définissez Emplacement de l'ID d'objet sur id.

  8. Cliquez sur Enregistrer.

  9. Cliquez sur Revenir aux paramètres du développeur pour revenir à la page Paramètres du développeur.

Configurer un point de terminaison "Mettre à jour un compte"

Pour configurer le point de terminaison "Mettre à jour un compte", procédez comme suit :

  1. Dans le volet CRM, accédez à la section Compte API.
  2. Pour Mettre à jour un point de terminaison de compte, cliquez sur Configurer. La page Configuration du point de terminaison de l'API générique s'affiche.
  3. Dans le champ URL, saisissez l'URL du compte à rechercher (par exemple, https://YOUR_ESPO_DOMAIN/api/v1/Contact).
  4. Pour Méthode, sélectionnez PUT.

  5. Pour configurer les paramètres de requête, procédez comme suit :

    1. Pour configurer le premier paramètre de requête, procédez comme suit :
      1. Pour Paramètres de la requête, cliquez sur Ajouter un champ. La boîte de dialogue Ajouter un champ s'affiche.
      2. Dans le champ Clé du champ, saisissez contactId.
      3. Dans le champ Valeur du champ, saisissez {PHONE_NUMBER}.
      4. Cliquez sur Enregistrer.

    2. Pour configurer le reste des paramètres de la requête, répétez l'étape précédente en utilisant les informations du tableau suivant. Vous avez déjà créé le premier paramètre de requête.

      Clé du paramètre Valeur du paramètre
      contactId {PHONE_NUMBER}
      phoneNumber New Caller

  6. Définissez l'emplacement des données de réponse sur data.

  7. Cliquez sur Enregistrer.

  8. Cliquez sur Revenir aux paramètres du développeur pour revenir à la page Paramètres du développeur.

Configurer les points de terminaison des enregistrements d'API

Cette section explique comment configurer les points de terminaison d'enregistrement d'API.

Configurer un point de terminaison "Find a record by query"

Pour configurer le point de terminaison de requête Find a record, procédez comme suit :

  1. Dans le volet CRM, accédez à la section Enregistrement de l'API.
  2. Pour Find a record by query endpoint (Trouver un enregistrement par point de terminaison de requête), cliquez sur Setup (Configurer). La page Configuration du point de terminaison de l'API générique s'affiche.
  3. Dans le champ URL, saisissez l'URL du compte à rechercher (par exemple, https://YOUR_ESPO_DOMAIN/api/v1/Case).
  4. Pour Méthode, sélectionnez GET.

  5. Pour configurer les paramètres de requête, procédez comme suit :

    1. Pour configurer le premier paramètre de requête, procédez comme suit :
      1. Pour Paramètres de la requête, cliquez sur Ajouter un champ. La boîte de dialogue Ajouter un champ s'affiche.
      2. Dans le champ Clé du champ, saisissez where[0][attribute].
      3. Dans le champ Valeur du champ, saisissez contactId.
      4. Cliquez sur Enregistrer.

    2. Pour configurer le reste des paramètres de la requête, répétez l'étape précédente en utilisant les informations du tableau suivant. Vous avez déjà créé le premier paramètre de requête.

      Clé de champ Valeur du champ
      where[0][attribute] contactId
      where[0][type] equals
      where[0][value] {ACCOUNT_ID}
      contactId {ACCOUNT_ID}
      sortBy createdAt
      asc false

  6. Dans le champ Emplacement des données de réponse, saisissez data.list.

  7. Cliquez sur Enregistrer.

  8. Cliquez sur Revenir aux paramètres du développeur pour revenir à la page Paramètres du développeur.

Configurer un point de terminaison "Find a record by ID"

Souvent utilisé dans les interactions basées sur le SDK, cela vous permet de transmettre un ID d'enregistrement spécifique auquel associer l'interaction. Pour configurer le point de terminaison "Find a record by ID" (Trouver un enregistrement par ID), procédez comme suit :

  1. Dans le volet CRM, accédez à la section Enregistrement de l'API.
  2. Pour le point de terminaison "Find a record by ID" (Rechercher un enregistrement par ID), cliquez sur Setup (Configurer). La page Configuration du point de terminaison de l'API générique s'affiche.
  3. Dans le champ URL, saisissez l'URL du compte à rechercher (par exemple, https://YOUR_ESPO_DOMAIN/api/v1/Case/{RECORD_ID}).
  4. Pour Méthode, sélectionnez GET.
  5. Dans le champ Emplacement des données de réponse, saisissez data.
  6. Cliquez sur Enregistrer.
  7. Cliquez sur Revenir aux paramètres du développeur pour revenir à la page Paramètres du développeur.

Configurer un point de terminaison "Créer un enregistrement"

Pour configurer le point de terminaison Create a record (Créer un enregistrement), procédez comme suit :

  1. Dans le volet CRM, accédez à la section Enregistrement de l'API.
  2. Pour Create a record endpoint (Créer un point de terminaison d'enregistrement), cliquez sur Setup (Configurer). La page Configuration du point de terminaison de l'API générique s'affiche.
  3. Dans le champ URL, saisissez l'URL du compte à rechercher (par exemple, https://YOUR_ESPO_DOMAIN/api/v1/Case).
  4. Pour Méthode, sélectionnez POST.

  5. Pour configurer les paramètres de requête, procédez comme suit :

    1. Pour configurer le premier paramètre de requête, procédez comme suit :
      1. Pour Paramètres de la requête, cliquez sur Ajouter un champ. La boîte de dialogue Ajouter un champ s'affiche.
      2. Dans le champ Clé du champ, saisissez description.
      3. Dans le champ Valeur du champ, saisissez CALL Session:{CALL_ID}.
      4. Cliquez sur Enregistrer.

    2. Pour configurer le reste des paramètres de la requête, répétez l'étape précédente en utilisant les informations du tableau suivant. Vous avez déjà créé le premier paramètre de requête.

      Clé du paramètre Valeur du paramètre
      description Call Session: {CALL_ID}
      name Inbound Call from {ANI}
      contactId {ACCOUNT_ID}
      status New
      cchatId {CHAT_ID}
      ccallId {CALL_ID}
      cChannel {CHANNEL}
      Type {SESSION_TYPE}

  6. Dans le champ Emplacement des données de réponse, saisissez data.

  7. Dans le champ Emplacement de l'ID d'objet, saisissez id.

  8. Cliquez sur Enregistrer.

  9. Cliquez sur Revenir aux paramètres du développeur pour revenir à la page Paramètres du développeur.

Configurer un point de terminaison "Mettre à jour un enregistrement"

Pour configurer le point de terminaison "Mettre à jour un enregistrement", procédez comme suit :

  1. Dans le volet CRM, accédez à la section Enregistrement de l'API.
  2. Pour Mettre à jour un point de terminaison d'enregistrement, cliquez sur Configurer. La page Configuration du point de terminaison de l'API générique s'affiche.
  3. Dans le champ URL, saisissez l'URL du compte à rechercher (par exemple, https://YOUR_ESPO_DOMAIN/api/v1/Case/{RECORD_ID}).
  4. Pour Méthode, sélectionnez PUT.

  5. Pour configurer les paramètres de requête, procédez comme suit :

    1. Pour configurer le premier paramètre de requête, procédez comme suit :
      1. Pour Paramètres de la requête, cliquez sur Ajouter un champ. La boîte de dialogue Ajouter un champ s'affiche.
      2. Dans le champ Clé du champ, saisissez parentId.
      3. Dans le champ Valeur du champ, saisissez {RECORD_ID}.
      4. Cliquez sur Enregistrer.

    2. Pour configurer le reste des paramètres de la requête, répétez l'étape précédente en utilisant les informations du tableau suivant. Vous avez déjà créé le premier paramètre de requête.

      Clé du paramètre Valeur du paramètre
      parentId {RECORD_ID}
      parentType Case
      status New
      description {TICKET_DESCRIPTION}

  6. Dans le champ Emplacement des données de réponse, saisissez data.

  7. Cliquez sur Enregistrer.

  8. Cliquez sur Revenir aux paramètres du développeur pour revenir à la page Paramètres du développeur.