Version préliminaire · Cette aide est encore en construction et sera enrichie progressivement.

Intégration · Administrateur

Configurer l’intégration personnalisée

Connecter votre propre système à echo via une API HTTP

Mise à jour: novembre 2026

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

Comment echo appelle votre point de terminaison

Fig. 1: Pour chaque recherche, echo envoie une requête GET à votre point de terminaison et attend en retour une liste JSON de contacts.

Requête

echo envoie une requête GET au point de terminaison des contacts avec deux paramètres de requête :

ParamètreValeur
queryLa valeur recherchée ; voir le tableau ci-dessous.
typephone, mail, name ou id
typeQuand echo l’envoiequery contient
phoneAppel entrant ou recherche d’un numéro de téléphoneLe numéro au format international, p. ex. +41441234567 (encodé dans l’URL en %2B41441234567)
mailRecherche d’une adresse e-mailL’adresse e-mail, p. ex. anna.muster@example.com
nameRecherche d’un nomLe terme saisi, p. ex. Anna Muster
idecho recharge un contact trouvé auparavantL’Id de cette personne ou entreprise

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 null ou 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=id et 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 :

Configurer l’intégration

Fig. 2: Paramètres → Intégration personnalisée avec un point de terminaison configuré.
1

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.

2

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-Key ou Authorization.
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 ajoute query et type ; 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’Id de 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.
3

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

  1. 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"
  1. Répétez avec type=name et type=mail, ainsi qu’avec une valeur inexistante (résultat attendu : []).
  2. 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}.