Version préliminaire · Cette aide est encore en construction et sera enrichie progressivement.
Configurer l’intégration personnalisée
Connecter votre propre système à echo via une API HTTP
L’intégration personnalisée vous permet de connecter un système pour lequel echo ne propose pas d’intégration prête à l’emploi – par exemple un CRM développé en interne ou une solution métier. Vous fournissez un point de terminaison HTTP qui répond aux requêtes d’echo avec des personnes et des entreprises dans un format JSON défini. echo l’utilise alors comme toute autre intégration pour identifier les appelants et rechercher des contacts, et peut relier chaque résultat à votre système.
L’intégration est configurée une seule fois par un administrateur et s’applique à toute l’organisation. Tous les utilisateurs voient les mêmes données provenant de votre point de terminaison.
Prérequis
- L’intégration personnalisée est activée pour votre organisation. Si elle n’apparaît pas dans le catalogue sous Paramètres → Intégrations, contactez le support echo (s’ouvre dans un nouvel onglet).
- Elle est ajoutée sous Paramètres → Intégrations (voir Fonctionnement des intégrations).
- Vous êtes connecté à echo en tant qu’administrateur.
- Votre point de terminaison est accessible depuis Internet en HTTPS et respecte le contrat décrit ci-dessous.
Comment echo appelle votre point de terminaison
Requête
echo envoie une requête GET au point de terminaison des contacts avec deux paramètres de requête :
Si Nom de l’en-tête de la clé API et Clé API sont renseignés, echo ajoute cet en-tête à chaque requête :
<Nom de l’en-tête de la clé API>: <Clé API>
Exemple de requête complète :
GET https://crm.example.com/api/contacts?query=%2B41441234567&type=phone
X-Api-Key: 3f9a7c2e1b
echo n’envoie l’en-tête que si les deux champs sont remplis. Si votre point de terminaison attend Authorization: Bearer … ou Authorization: Basic …, saisissez Authorization comme nom d’en-tête et la valeur complète, y compris Bearer ou Basic , comme clé API. Les autres méthodes (connexion OAuth ou certificats client, par exemple) ne sont pas prises en charge.
Réponse
Pour phone, mail et name, répondez avec le statut HTTP 200 et un tableau JSON. Chaque élément décrit un résultat et contient une Person, une Company ou les deux (une personne avec son entreprise). S’il n’y a aucun résultat, renvoyez un tableau vide [].
[
{
"Person": {
"Id": 1042,
"FirstName": "Anna",
"LastName": "Muster",
"Emails": ["anna.muster@example.com"],
"PhoneNumbers": ["+41 44 123 45 67"],
"Mobiles": ["+41 79 123 45 67"],
"Faxes": [],
"Websites": [],
"Remarks": ["Préfère l’e-mail"],
"Addresses": [
{
"Street": "Musterstrasse",
"HouseNumber": "12",
"PostCode": "8000",
"City": "Zürich",
"Canton": "ZH",
"Country": "Suisse"
}
]
},
"Company": {
"Id": 2001,
"Name": "Muster AG",
"Emails": ["info@example.com"],
"PhoneNumbers": ["+41 44 123 45 00"],
"Mobiles": [],
"Faxes": [],
"Websites": ["https://www.example.com"],
"Remarks": [],
"Addresses": []
}
}
]
Pour type=id, répondez avec un seul objet de même structure (pas un tableau), ou null si l’ID n’existe plus.
Les champs :
- Person / Company
- L’un ou l’autre peut être
nullou absent. Un élément sans aucun des deux est ignoré. - Id
- Obligatoire. L’ID de la personne ou de l’entreprise dans votre système. echo le renvoie avec
type=idet l’insère dans les liens profonds. Utilisez des ID numériques : actuellement, echo ne recharge un contact par son ID que si cet ID est un nombre. - FirstName, LastName
- Nom de la personne. Obligatoire pour une personne.
- Name
- Nom de l’entreprise. Obligatoire pour une entreprise.
- Emails, PhoneNumbers, Mobiles, Faxes, Websites, Remarks
- Listes de chaînes ; facultatives, peuvent être vides ou
null. Numéros de téléphone de préférence au format international (+41 …) ; les numéros sans indicatif pays sont interprétés selon votre région par défaut des numéros de téléphone. - Addresses
- Liste d’adresses avec
Street,HouseNumber,PostCode,City,Canton,Country(toutes des chaînes facultatives).
Le schéma JSON complet peut être téléchargé sur la page de paramètres, sous Quelle réponse echo attend-il ?.
Règles à respecter par votre point de terminaison :
- Filtrez vous-même. echo affiche ce que vous renvoyez. Pour
phone, ne renvoyez que les contacts qui ont ce numéro. - Répondez toujours avec succès. Tout statut autre que 2xx (y compris
404pour « introuvable ») ou une réponse qui n’est pas du JSON valide est une erreur – et une erreur peut faire échouer toute l’identification de l’appelant, y compris pour les autres intégrations. Répondez « rien trouvé » par[]. - Répondez rapidement. echo attend toutes les intégrations avant d’afficher le résultat ; un point de terminaison lent retarde donc chaque identification d’appelant.
Configurer l’intégration
Ouvrir les paramètres
Ouvrez Paramètres → Intégration personnalisée. L’entrée apparaît dans le menu des paramètres dès que l’intégration est ajoutée.
Remplir les champs
- Nom
- Obligatoire, 50 caractères au plus 1. Le nom de votre système tel que les utilisateurs le voient dans echo, par exemple dans les liens Ouvrir la personne dans Muster CRM.
- Nom de l’en-tête de la clé API
- Facultatif 2. Nom de l’en-tête HTTP qui transporte la clé, p. ex.
X-Api-KeyouAuthorization. - Clé API
- Facultatif, 100 caractères au plus. La valeur de cet en-tête. echo l’enregistre de manière chiffrée et n’affiche ensuite qu’un espace réservé. Si vous ne touchez pas au champ, la clé enregistrée est conservée.
- Point de terminaison des contacts
- Obligatoire, 300 caractères au plus 3. URL complète de votre point de terminaison, p. ex.
https://crm.example.com/api/contacts. echo ajoutequeryettype; les paramètres déjà présents dans l’URL sont conservés. - URL du lien profond (personne)
- Facultatif, 250 caractères au plus 4. Adresse d’une personne dans votre système. echo remplace
{id}par l’Idde la personne, p. ex.https://crm.example.com/person/{id}. Sans cette URL, echo n’affiche pas de lien vers votre système pour les personnes. - URL du lien profond (entreprise)
- Facultatif, 250 caractères au plus. Idem pour les entreprises.
Enregistrer
Cliquez sur Enregistrer. Le bouton est actif dès que Nom et Point de terminaison des contacts sont remplis. echo ne teste pas le point de terminaison à l’enregistrement – testez-le comme décrit ci-dessous.
Tester la connexion
- Appelez votre point de terminaison comme le fait echo, par exemple avec
curl, et vérifiez qu’il renvoie le statut 200 et la structure JSON décrite ci-dessus :
curl -H "X-Api-Key: 3f9a7c2e1b" "https://crm.example.com/api/contacts?query=%2B41441234567&type=phone"
- Répétez avec
type=nameettype=mail, ainsi qu’avec une valeur inexistante (résultat attendu :[]). - Dans echo, recherchez un nom ou un numéro de téléphone qui existe dans votre système. Le contact doit apparaître ; si des liens profonds sont configurés, le lien vers votre système s’affiche aussi sur le contact.
Dépannage
La page indique que l’intégration personnalisée n’est pas activée. Ajoutez-la d’abord sous Paramètres → Intégrations.
L’intégration affiche Non configurée. Nom ou Point de terminaison des contacts est vide. echo n’appelle votre point de terminaison qu’une fois les deux enregistrés.
Depuis l’ajout de l’intégration, plus aucun appelant n’est reconnu. Votre point de terminaison répond probablement par une erreur (p. ex. 401 à cause d’une clé erronée, 404, 500, délai dépassé ou JSON invalide). Consultez les journaux de votre point de terminaison et testez-le avec curl comme ci-dessus. En attendant la correction, vous pouvez retirer l’intégration.
Les contacts de votre système n’apparaissent pas. Vérifiez que votre point de terminaison filtre correctement pour chaque type, qu’il trouve les numéros au format international (+41…) et que le JSON utilise les noms de champs indiqués ci-dessus.
Un contact apparaît en double. echo ne regroupe un résultat avec un contact d’une autre intégration que si le nom est similaire et que le numéro de téléphone ou l’adresse e-mail concordent. Assurez-vous que vos données contiennent ces informations.
Un contact est trouvé mais ne peut pas être rechargé. Utilisez des ID numériques et assurez-vous que votre point de terminaison répond à type=id avec un seul objet, pour les ID de personnes comme d’entreprises.
Aucun lien vers votre système. Renseignez URL du lien profond (personne) ou URL du lien profond (entreprise) et utilisez l’espace réservé {id}.