Vorschau · Diese Hilfe befindet sich noch im Aufbau und wird laufend erweitert.
Benutzerdefinierte Integration konfigurieren
Ihr eigenes System über eine HTTP-API mit echo verbinden
Mit der benutzerdefinierten Integration binden Sie ein System an, für das echo keine fertige Integration hat – zum Beispiel ein selbst entwickeltes CRM oder eine Branchenlösung. Sie stellen einen HTTP-Endpunkt bereit, der die Anfragen von echo mit Personen und Firmen in einem festen JSON-Format beantwortet. echo nutzt ihn dann wie jede andere Integration für die Anrufererkennung und die Kontaktsuche und kann jedes Ergebnis mit Ihrem System verlinken.
Die Integration wird einmal von einem Administrator eingerichtet und gilt für die ganze Organisation. Alle Benutzer sehen dieselben Daten aus Ihrem Endpunkt.
Voraussetzungen
- Die benutzerdefinierte Integration ist für Ihre Organisation freigeschaltet. Fehlt sie im Katalog unter Einstellungen → Integrationen, wenden Sie sich an den echo Support (öffnet in neuem Tab).
- Sie ist unter Einstellungen → Integrationen hinzugefügt (siehe So funktionieren Integrationen).
- Sie sind in echo als Administrator angemeldet.
- Ihr Endpunkt ist aus dem Internet per HTTPS erreichbar und hält sich an die unten beschriebene Schnittstelle.
So ruft echo Ihren Endpunkt auf
Anfrage
echo sendet eine GET-Anfrage an den Kontakte-Endpunkt mit zwei Abfrageparametern:
Sind API-Schlüssel Header-Name und API-Schlüssel ausgefüllt, ergänzt echo jede Anfrage um diesen Header:
<API-Schlüssel Header-Name>: <API-Schlüssel>
Beispiel einer vollständigen Anfrage:
GET https://crm.example.com/api/contacts?query=%2B41441234567&type=phone
X-Api-Key: 3f9a7c2e1b
echo sendet den Header nur, wenn beide Felder ausgefüllt sind. Erwartet Ihr Endpunkt Authorization: Bearer … oder Authorization: Basic …, tragen Sie Authorization als Header-Name und den vollständigen Wert inklusive Bearer bzw. Basic als API-Schlüssel ein. Andere Verfahren (etwa eine OAuth-Anmeldung oder Client-Zertifikate) werden nicht unterstützt.
Antwort
Für phone, mail und name antworten Sie mit HTTP-Status 200 und einem JSON-Array. Jedes Element beschreibt ein Ergebnis und enthält eine Person, eine Company oder beides (eine Person zusammen mit ihrer Firma). Gibt es keinen Treffer, liefern Sie ein leeres Array [].
[
{
"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": ["Bevorzugt E-Mail"],
"Addresses": [
{
"Street": "Musterstrasse",
"HouseNumber": "12",
"PostCode": "8000",
"City": "Zürich",
"Canton": "ZH",
"Country": "Schweiz"
}
]
},
"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": []
}
}
]
Für type=id antworten Sie mit einem Objekt derselben Struktur (kein Array) oder mit null, wenn die ID nicht mehr existiert.
Die Felder:
- Person / Company
- Beide dürfen
nullsein oder fehlen. Ein Element ohne beides wird ignoriert. - Id
- Pflicht. Die ID der Person oder Firma in Ihrem System. echo sendet sie mit
type=idzurück und setzt sie in die Deep Links ein. Verwenden Sie numerische IDs: echo lädt Kontakte derzeit nur dann per ID neu, wenn die ID eine Zahl ist. - FirstName, LastName
- Name der Person. Pflicht bei einer Person.
- Name
- Firmenname. Pflicht bei einer Firma.
- Emails, PhoneNumbers, Mobiles, Faxes, Websites, Remarks
- Listen von Texten; optional, dürfen leer oder
nullsein. Telefonnummern idealerweise im internationalen Format (+41 …); Nummern ohne Ländervorwahl werden mit Ihrer Standardregion für Telefonnummern interpretiert. - Addresses
- Liste von Adressen mit
Street,HouseNumber,PostCode,City,Canton,Country(alles optionale Texte).
Das vollständige JSON-Schema können Sie auf der Einstellungsseite unter Welche Antwort erwartet echo? herunterladen.
Regeln für Ihren Endpunkt:
- Selbst filtern. echo zeigt, was Sie zurückgeben. Liefern Sie für
phonenur Kontakte mit genau dieser Nummer. - Immer erfolgreich antworten. Jeder Status ausser 2xx (auch
404für «nicht gefunden») oder eine Antwort, die kein gültiges JSON ist, gilt als Fehler – und ein Fehler kann die ganze Anrufererkennung scheitern lassen, auch für die anderen Integrationen. Beantworten Sie «nichts gefunden» mit[]. - Schnell antworten. echo wartet auf alle Integrationen, bevor es das Ergebnis zeigt. Ein langsamer Endpunkt verzögert also jede Anrufererkennung.
Integration einrichten
Einstellungen öffnen
Öffnen Sie Einstellungen → Benutzerdefinierte Integration. Der Eintrag erscheint im Einstellungsmenü, sobald die Integration hinzugefügt ist.
Felder ausfüllen
- Name
- Pflicht, bis 50 Zeichen 1. Der Name Ihres Systems, wie ihn die Benutzer in echo sehen, z. B. bei den Links Person in Muster CRM öffnen.
- API-Schlüssel Header-Name
- Optional 2. Name des HTTP-Headers, der den Schlüssel trägt, z. B.
X-Api-KeyoderAuthorization. - API-Schlüssel
- Optional, bis 100 Zeichen. Der Wert dieses Headers. echo speichert ihn verschlüsselt und zeigt danach nur einen Platzhalter. Lassen Sie das Feld unberührt, bleibt der gespeicherte Schlüssel erhalten.
- Kontakte-Endpunkt
- Pflicht, bis 300 Zeichen 3. Vollständige URL Ihres Endpunkts, z. B.
https://crm.example.com/api/contacts. echo hängtqueryundtypean; Abfrageparameter, die bereits in der URL stehen, bleiben erhalten. - Person Deep Link URL
- Optional, bis 250 Zeichen 4. Adresse einer Person in Ihrem System. echo ersetzt
{id}durch dieIdder Person, z. B.https://crm.example.com/person/{id}. Ohne diese Angabe zeigt echo bei Personen keinen Link zu Ihrem System. - Firma Deep Link URL
- Optional, bis 250 Zeichen. Dasselbe für Firmen.
Speichern
Klicken Sie auf Speichern. Die Schaltfläche ist aktiv, sobald Name und Kontakte-Endpunkt ausgefüllt sind. echo prüft den Endpunkt beim Speichern nicht – testen Sie ihn wie unten beschrieben.
Verbindung testen
- Rufen Sie Ihren Endpunkt so auf, wie echo es tut, zum Beispiel mit
curl, und prüfen Sie, ob er Status 200 und die oben beschriebene JSON-Struktur liefert:
curl -H "X-Api-Key: 3f9a7c2e1b" "https://crm.example.com/api/contacts?query=%2B41441234567&type=phone"
- Wiederholen Sie den Test mit
type=nameundtype=mailsowie mit einem Wert, den es nicht gibt (erwartet:[]). - Suchen Sie in echo nach einem Namen oder einer Telefonnummer, die es in Ihrem System gibt. Der Kontakt sollte erscheinen; mit Deep Links wird beim Kontakt auch der Link zu Ihrem System angezeigt.
Fehlerbehebung
Die Seite meldet, dass die benutzerdefinierte Integration nicht aktiviert ist. Fügen Sie sie zuerst unter Einstellungen → Integrationen hinzu.
Die Integration zeigt «Nicht konfiguriert». Name oder Kontakte-Endpunkt ist leer. echo ruft Ihren Endpunkt erst auf, wenn beides gespeichert ist.
Seit dem Hinzufügen der benutzerdefinierten Integration werden Anrufer gar nicht mehr erkannt. Ihr Endpunkt antwortet vermutlich mit einem Fehler (z. B. 401 wegen eines falschen Schlüssels, 404, 500, Zeitüberschreitung oder ungültiges JSON). Prüfen Sie die Logs Ihres Endpunkts und testen Sie ihn wie oben mit curl. Bis das Problem behoben ist, können Sie die Integration entfernen.
Kontakte aus Ihrem System erscheinen nicht. Prüfen Sie, ob Ihr Endpunkt für jeden type richtig filtert, ob er Telefonnummern für die Nummer im internationalen Format (+41…) findet und ob das JSON die oben genannten Feldnamen verwendet.
Ein Kontakt erscheint doppelt. echo führt ein Ergebnis nur dann mit einem Kontakt aus einer anderen Integration zusammen, wenn der Name ähnlich ist und Telefonnummer oder E-Mail-Adresse übereinstimmen. Stellen Sie sicher, dass Ihre Daten diese Angaben enthalten.
Ein Kontakt wird gefunden, lässt sich aber nicht neu laden. Verwenden Sie numerische IDs und stellen Sie sicher, dass Ihr Endpunkt type=id für Personen- und Firmen-IDs mit einem einzelnen Objekt beantwortet.
Kein Link zu Ihrem System. Füllen Sie Person Deep Link URL bzw. Firma Deep Link URL aus und verwenden Sie den Platzhalter {id}.