Vorschau · Diese Hilfe befindet sich noch im Aufbau und wird laufend erweitert.

Integration · Administrator

Benutzerdefinierte Integration konfigurieren

Ihr eigenes System über eine HTTP-API mit echo verbinden

Stand: November 2026

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

So ruft echo Ihren Endpunkt auf

Abb. 1: Für jede Suche sendet echo eine GET-Anfrage an Ihren Endpunkt und erwartet eine JSON-Liste von Kontakten zurück.

Anfrage

echo sendet eine GET-Anfrage an den Kontakte-Endpunkt mit zwei Abfrageparametern:

ParameterWert
queryDer Suchwert; siehe Tabelle unten.
typephone, mail, name oder id
typeWann echo ihn sendetquery enthält
phoneEingehender Anruf oder Suche nach einer TelefonnummerDie Nummer im internationalen Format, z. B. +41441234567 (URL-codiert als %2B41441234567)
mailSuche nach einer E-Mail-AdresseDie E-Mail-Adresse, z. B. anna.muster@example.com
nameSuche nach einem NamenDen eingegebenen Suchbegriff, z. B. Anna Muster
idecho lädt einen zuvor gefundenen Kontakt neuDie Id dieser Person oder Firma

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 null sein oder fehlen. Ein Element ohne beides wird ignoriert.
Id
Pflicht. Die ID der Person oder Firma in Ihrem System. echo sendet sie mit type=id zurü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 null sein. 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:

Integration einrichten

Abb. 2: Einstellungen → Benutzerdefinierte Integration mit einem konfigurierten Endpunkt.
1

Einstellungen öffnen

Öffnen Sie Einstellungen → Benutzerdefinierte Integration. Der Eintrag erscheint im Einstellungsmenü, sobald die Integration hinzugefügt ist.

2

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-Key oder Authorization.
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ängt query und type an; 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 die Id der 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.
3

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

  1. 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"
  1. Wiederholen Sie den Test mit type=name und type=mail sowie mit einem Wert, den es nicht gibt (erwartet: []).
  2. 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}.