À qui s'adresse cette page
Cette page s'adresse à l'équipe de développement de votre ERP ou CRM lorsque votre système ne fait pas partie des intégrations natives (Dynamics 365, Salesforce, HubSpot, Pipedrive, Loji). Le connecteur REST générique de CX-Engine permet de connecter n'importe quel système exposant une API, à condition que cette API implémente un petit ensemble de routes spécifiques, afin que le Middleware puisse l'interroger et y écrire lors des événements PBX (appels entrants, appels sortants, sessions de chat).
Vous n'avez pas besoin de reproduire le format de l'API de CX-Engine elle-même — le connecteur générique se configure visuellement (URL des points d'entrée, authentification, mapping des champs) depuis l'interface CX-Engine. L'essentiel est que votre système expose des routes permettant d'effectuer les opérations suivantes.
Authentification
Votre API doit supporter l'une des méthodes suivantes, ce sont celles avec lesquelles le connecteur générique peut être configuré :
| Méthode | Description |
|---|---|
| OAuth 2.0 Client Credentials | Authentification serveur à serveur via une paire client_id / client_secret. Recommandée pour les configurations sans interface. |
| Basic Auth (HTTP) | Nom d'utilisateur / mot de passe envoyés à chaque requête. |
| Clé API | Clé statique envoyée en en-tête ou en paramètre de requête. |
Quelle que soit la méthode choisie, les identifiants sont saisis une seule fois dans le menu Intégrations de CX-Engine et utilisés pour chaque requête suivante vers votre API.
Routes requises
Remontée de fiche (Contact Lookup) — recherche par numéro de téléphone ou email
Usage : Appelée lors de la remontée de fiche lorsqu'un appel sonne sur le PBX, afin que CX-Engine puisse afficher la fiche client correspondante à l'agent avant même qu'il ne décroche.
Votre API a besoin d'une route acceptant un numéro de téléphone et/ou une adresse email, et renvoyant les contacts correspondants.
Format suggéré
GET /contacts/search?phone={phone}&email={email}
| Champ de réponse | Description |
|---|---|
id |
Identifiant unique du contact dans votre système |
first_name / last_name |
Nom du contact |
email |
Email du contact |
phone_business / phone_mobile |
Numéros de téléphone, pour permettre à CX-Engine de matcher sur l'un ou l'autre |
company |
Nom de l'entreprise, affiché dans la remontée de fiche |
entity_url |
URL directe vers la fiche du contact dans votre système, utilisée pour l'ouvrir en un clic |
Si un appel arrive et qu'aucun contact ne correspond, renvoyez un
404. CX-Engine utilise ce code pour basculer sur son mode « contact factice » (dummy), afin que la journalisation de l'appel puisse tout de même se poursuivre.
Création de contact
Usage : Appelée lorsqu'un agent choisit de créer une nouvelle fiche pour un appelant non reconnu, directement depuis la remontée de fiche CX-Engine.
Format suggéré
POST /contacts
| Champ | Requis | Description |
|---|---|---|
last_name |
oui | Nom |
first_name |
non | Prénom |
email |
non | Adresse email |
phone_business / phone_mobile |
non | Numéros de téléphone |
call_direction |
non | inbound ou outbound — sens de l'appel à l'origine de la création |
Votre API doit renvoyer la fiche créée (a minima son id) afin que CX-Engine puisse y rattacher l'appel.
Recherche d'utilisateur — trouver un utilisateur par email
Usage : Le PBX ne fournit que l'adresse email de l'agent. Si la journalisation des appels dans votre système nécessite un user_id pour rattacher l'appel à un utilisateur/agent précis, CX-Engine a besoin d'une route pour résoudre cet email vers votre identifiant utilisateur interne.
Format suggéré
GET /users/search?email={email}
| Champ de réponse | Description |
|---|---|
id |
Identifiant unique de l'utilisateur dans votre système |
email |
Adresse email de l'utilisateur |
Journal des appels (Call Logging) — enregistrer un appel terminé
Usage : Appelée lorsqu'un appel se termine sur le PBX, afin qu'il apparaisse comme une activité/un historique rattaché à la bonne fiche dans votre système. C'est le cœur de la fonctionnalité de journalisation automatique des appels.
Format suggéré
POST /calls
| Champ | Description |
|---|---|
direction |
inbound, outbound, ou internal |
status |
ex. completed, no-answer, busy |
number_from / number_to |
Numéros appelant et appelé |
duration |
Durée de l'appel |
start_time / end_time |
Horodatages de l'appel (UTC) |
agent_email |
Email de l'agent ayant traité l'appel |
user_id |
Identifiant utilisateur interne de l'agent, résolu via la route de recherche d'utilisateur ci-dessus, si votre fiche d'appel en a besoin |
recording_url |
URL de l'enregistrement de l'appel, si votre offre inclut l'enregistrement |
linked_contact_id |
L'id du contact renvoyé par la route de remontée de fiche, si une correspondance a été trouvée |
Mise à jour d'un appel
Usage : Certaines données ne sont pas encore disponibles lorsque l'appel se termine — des informations PBX supplémentaires récupérées dans un second temps, ou une transcription/un résumé IA généré de façon asynchrone. Votre API a besoin d'une route pour mettre à jour la fiche d'appel déjà créée, plutôt que d'exiger un nouveau POST pour chaque donnée supplémentaire.
Format suggéré
PUT /calls/{id}
Accepte les mêmes champs que POST /calls, appliqués en mise à jour partielle de l'appel identifié par {id} — l'identifiant renvoyé par votre système lors de la journalisation initiale de l'appel.
Champs IA
Si votre offre CX-Engine inclut le module Insights AI, les appels sont également enrichis avec des données générées par IA — transcription, résumé, sentiment, sujets, etc. Ces données ne sont généralement pas prêtes lorsque l'appel se termine, elles sont donc envoyées via la route de mise à jour PUT /calls/{id} ci-dessus une fois la transcription terminée. Consultez les champs AI & Transcription dans Configurer le Middleware pour la liste complète des champs que vous pouvez choisir de mapper et de stocker.
Journal des chats (optionnel)
Usage : Si votre PBX / centre de contact gère également le chat en direct, le même principe s'applique — une route pour enregistrer une session de chat terminée, rattachée à un contact.
POST /chats
| Champ | Description |
|---|---|
email |
Adresse email du client, utilisée pour matcher ou créer un contact |
number_external |
Identifiant externe du client, si aucun email n'est disponible |
chat_messages |
Transcription ou résumé de la conversation |
start_time / end_time |
Horodatages du chat |
agent_email |
Agent ayant traité le chat |
Conventions de réponse
- Utilisez les codes de statut HTTP standards :
200/201pour un succès,4xxpour les erreurs client (requête invalide, ressource introuvable),401/403pour les erreurs d'authentification/autorisation. - Renvoyez du JSON pour chaque réponse, y compris les erreurs.
- Pour les routes de liste ou de recherche, renvoyez un tableau vide plutôt qu'un
404en l'absence de résultat. La route de remontée de fiche fait exception : renvoyez un404pour permettre à CX-Engine de basculer sur son mode « contact factice » (voir ci-dessus).
Étapes suivantes
Une fois que votre API expose ces routes, un administrateur peut configurer la connexion depuis le menu Intégrations de CX-Engine — voir Connecter l'intégration CRM — puis faire correspondre les champs de votre API avec ceux de CX-Engine depuis le menu CRM Connector > Settings — voir Configurer le Middleware.