EspoCRM-Referenzimplementierung

In diesem Dokument wird eine Beispielintegration mit einem benutzerdefinierten CRM für die Contact Center AI Platform (CCAI Platform) mit EspoCRM beschrieben. EspoCRM ist eine kostenlose Open-Source-CRM-Anwendung, mit der Unternehmen Vertrieb, Marketing und Kundensupport über eine anpassbare Benutzeroberfläche verwalten können. Es bietet Funktionen wie Kontaktverwaltung, Aktivitäts-Tracking, Vertriebsautomatisierung und Inventarverwaltung mit Optionen für Self-Hosting oder Cloud-Bereitstellung.

Informationen zum Einrichten einer eigenen Instanz von EspoCRM finden Sie auf der EspoCRM-Installationsseite.

Hinweis

Gehen Sie dazu so vor:

  • Konfigurieren Sie Ihre Firewall so, dass Traffic von der CCAI-Plattform zugelassen wird.

  • Erstellen Sie einen API-Nutzer in Ihrer EspoCRM-Instanz, z. B. google_integration_user. Weitere Informationen finden Sie in der EspoCRM-Dokumentation unter API.

  • Erstellen Sie in Ihrer EspoCRM-Instanz eine Rolle mit den Aktionen Create (Erstellen), Read (Lesen) und Update (Aktualisieren), die auf Folgendes zugreifen:

    • Kontakte: Anrufer suchen oder erstellen
    • Fälle: zum Suchen nach und Protokollieren von Tickets

    Weitere Informationen finden Sie in der ExpoCRM-Dokumentation unter Rollenverwaltung.

Verbindung von EspoCRM zur CCAI Platform konfigurieren

So konfigurieren Sie eine Verbindung von EspoCRM zur CCAI Platform:

  1. Klicken Sie im CCAI Platform-Portal auf Einstellungen > Entwicklereinstellungen. Wenn Sie das Menü Einstellungen nicht sehen, klicken Sie auf das Menü.
  2. Wählen Sie für Agent Platform (Agent-Plattform) die Option Custom CRM (Benutzerdefiniertes CRM) aus.
  3. Klicken Sie auf den Ein/Aus-Schalter CRM im CCAI Platform-Portal anzeigen, um ihn auf „Ein“ zu stellen.
  4. Geben Sie im Feld Angezeigte URL die URL ein, die in das CCAI Platform-Portal eingebettet werden soll, z. B. https://YOUR_ESPO_DOMAIN/#Case/view/{RECORD_ID}.
  5. Wählen Sie für CRM-Suchmethode die Option Allgemeine API aus.
  6. So authentifizieren Sie sich mit einem benutzerdefinierten Header:
    1. Wählen Sie im Abschnitt Authentifizierungsmethode die Option Benutzerdefinierte Kopfzeile aus.
    2. Klicken Sie auf Feld hinzufügen. Das Dialogfeld Feld hinzufügen wird angezeigt.
      1. Geben Sie im Feld Feldschlüssel den Wert X-Api-Key ein.
      2. Geben Sie im Feld Feldwert den API-Schlüssel ein, der generiert wurde, als Sie einen API-Nutzer in Ihrem EspoCRM erstellt haben.
      3. Klicken Sie auf Speichern.
  7. So legen Sie die CRM-Such-URL fest:
    1. Geben Sie im Abschnitt CRM lookup URL (CRM-Such-URL) im Feld Record lookup URL (URL für die Datensatzsuche) die URL zum Suchen eines Datensatzes ein, z. B. https://YOUR_ESPO_DOMAIN/#Case/view/{RECORD_ID}.
    2. Geben Sie im Feld URL für die Kontosuche die URL für die Kontosuche ein, z. B. https://YOUR_ESPO_DOMAIN/#Contact/view/{ACCOUNT_ID}.
    3. Klicken Sie auf Speichern. ## API-Endpunkte konfigurieren

Konfigurieren Sie Endpunkte, die mit EspoCRM kompatibel sind, damit Ihre Integration die Komponenten zum Nachschlagen von Konten (Kontakten) und Datensätzen (Vorgängen) enthält. Weitere Informationen zu kompatiblen Variablen finden Sie in der EspoCRM-Dokumentation unter API Overview.

API-Kontoendpunkte konfigurieren

In diesem Abschnitt wird erläutert, wie Sie API-Kontoendpunkte konfigurieren.

Endpunkt „Konto anhand von Abfrage suchen“ konfigurieren

So konfigurieren Sie den Find an account by query endpoint:

  1. Klicken Sie in der CCAI-Plattform auf Einstellungen > Entwicklereinstellungen. Wenn Sie das Menü Einstellungen nicht sehen, klicken Sie auf das Menü.
  2. Rufen Sie im Bereich CRM den Abschnitt API-Konto auf.
  3. Klicken Sie für den Endpunkt zum Suchen eines Kontos anhand einer Anfrage auf Einrichtung. Die Seite Generic API Endpoint Setup (Einrichtung des generischen API-Endpunkts) wird angezeigt.
  4. Geben Sie im Feld URL die URL ein, über die ein Konto gesucht werden soll, z. B. https://YOUR_ESPO_DOMAIN/api/v1/Contact.
  5. Wählen Sie für Methode die Option GET aus.

  6. So konfigurieren Sie Anfrageparameter:

    1. So konfigurieren Sie den ersten Anfrageparameter:
      1. Klicken Sie auf Feld hinzufügen. Das Dialogfeld Feld hinzufügen wird angezeigt.
      2. Geben Sie im Feld Feldschlüssel den Wert where[0][attribute] ein.
      3. Geben Sie im Feld Feldwert den Wert phoneNumber ein.
      4. Klicken Sie auf Speichern.

    2. Wiederholen Sie die vorherigen Schritte mit den Informationen in der folgenden Tabelle, um die restlichen Anfrageparameter zu konfigurieren. Sie haben den ersten Anfrageparameter bereits erstellt.

      Feldschlüssel Feldwert
      where[0][attribute] phoneNumber
      where[0][type] equals
      where[0][value] {PHONE_NUMBER}
      sortBy createdAt
      asc false

  7. Geben Sie im Feld Speicherort der Antwortdaten den Wert data.list ein.

  8. Klicken Sie auf Speichern.

  9. Klicken Sie auf Zurück zu den Entwicklereinstellungen, um zur Seite Entwicklereinstellungen zurückzukehren.

Endpunkt zum Suchen eines Kontos anhand der ID konfigurieren

So konfigurieren Sie den Endpunkt „Konto anhand der ID suchen“:

  1. Rufen Sie im Bereich CRM den Abschnitt API-Konto auf.
  2. Klicken Sie für den Endpunkt zum Suchen eines Kontos nach ID auf Einrichtung. Die Seite Generic API Endpoint Setup (Einrichtung des generischen API-Endpunkts) wird angezeigt.
  3. Geben Sie im Feld URL die URL ein, über die ein Konto gesucht werden soll, z. B. https://YOUR_ESPO_DOMAIN/api/v1/Contact/{ACCOUNT_ID}.
    1. Wählen Sie für Methode die Option GET aus.
  4. Legen Sie für Speicherort der Antwortdaten den Wert data fest.
  5. Klicken Sie auf Speichern.
  6. Klicken Sie auf Return to developer settings (Zu Entwicklereinstellungen zurückkehren), um zur Seite Developer Settings (Entwicklereinstellungen) zurückzukehren.

Endpunkt „Konto erstellen“ konfigurieren

So konfigurieren Sie den Create an account-Endpunkt:

  1. Rufen Sie im Bereich CRM den Abschnitt API-Konto auf.
  2. Klicken Sie für Kontoendpunkt erstellen auf Einrichtung. Die Seite Generic API Endpoint Setup (Einrichtung des generischen API-Endpunkts) wird angezeigt.
  3. Geben Sie im Feld URL die URL ein, über die ein Konto gesucht werden soll, z. B. https://YOUR_ESPO_DOMAIN/api/v1/Contact.
  4. Wählen Sie für Methode die Option POST aus.

  5. So konfigurieren Sie Anfrageparameter:

    1. So konfigurieren Sie den ersten Anfrageparameter:
      1. Klicken Sie unter Anfrageparameter auf Feld hinzufügen. Das Dialogfeld Feld hinzufügen wird angezeigt.
      2. Geben Sie im Feld Feldschlüssel den Wert phoneNumber ein.
      3. Geben Sie im Feld Feldwert den Wert {PHONE_NUMBER} ein.
      4. Klicken Sie auf Speichern.

    2. Wiederholen Sie den vorherigen Schritt, um die restlichen Anfrageparameter zu konfigurieren. Verwenden Sie dazu die Informationen in der folgenden Tabelle. Sie haben den ersten Anfrageparameter bereits erstellt.

      Parameterschlüssel Parameterwert
      phoneNumber {PHONE_NUMBER}
      firstName New Caller
      lastName {CALL_ID}
      name New Caller {CALL_ID}

  6. Legen Sie den Speicherort der Antwortdaten auf data fest.

  7. Legen Sie Speicherort der Objekt-ID auf id fest.

  8. Klicken Sie auf Speichern.

  9. Klicken Sie auf Return to developer settings (Zu Entwicklereinstellungen zurückkehren), um zur Seite Developer Settings (Entwicklereinstellungen) zurückzukehren.

Endpunkt zum Aktualisieren eines Kontos konfigurieren

So konfigurieren Sie den Update an account endpoint:

  1. Rufen Sie im Bereich CRM den Abschnitt API-Konto auf.
  2. Klicken Sie unter Kontopunkt aktualisieren auf Einrichtung. Die Seite Generic API Endpoint Setup (Einrichtung des generischen API-Endpunkts) wird angezeigt.
  3. Geben Sie im Feld URL die URL ein, über die ein Konto gesucht werden soll, z. B. https://YOUR_ESPO_DOMAIN/api/v1/Contact.
  4. Wählen Sie für Methode die Option PUT aus.

  5. So konfigurieren Sie Anfrageparameter:

    1. So konfigurieren Sie den ersten Anfrageparameter:
      1. Klicken Sie unter Anfrageparameter auf Feld hinzufügen. Das Dialogfeld Feld hinzufügen wird angezeigt.
      2. Geben Sie im Feld Feldschlüssel den Wert contactId ein.
      3. Geben Sie im Feld Feldwert den Wert {PHONE_NUMBER} ein.
      4. Klicken Sie auf Speichern.

    2. Wiederholen Sie den vorherigen Schritt, um die restlichen Anfrageparameter zu konfigurieren. Verwenden Sie dazu die Informationen in der folgenden Tabelle. Sie haben den ersten Anfrageparameter bereits erstellt.

      Parameterschlüssel Parameterwert
      contactId {PHONE_NUMBER}
      phoneNumber New Caller

  6. Legen Sie den Speicherort der Antwortdaten auf data fest.

  7. Klicken Sie auf Speichern.

  8. Klicken Sie auf Return to developer settings (Zu Entwicklereinstellungen zurückkehren), um zur Seite Developer Settings (Entwicklereinstellungen) zurückzukehren.

API-Datensatzendpunkte konfigurieren

In diesem Abschnitt wird erläutert, wie Sie API-Aufzeichnungs-Endpunkte konfigurieren.

Endpunkt „Datensatz anhand von Abfrage suchen“ konfigurieren

So konfigurieren Sie den Find a record by query endpoint (Endpunkt zum Suchen eines Datensatzes anhand einer Abfrage):

  1. Rufen Sie im Bereich CRM den Abschnitt API-Datensatz auf.
  2. Klicken Sie für Einen Datensatz über den Abfrageendpunkt finden auf Einrichtung. Die Seite Generic API Endpoint Setup (Einrichtung des generischen API-Endpunkts) wird angezeigt.
  3. Geben Sie im Feld URL die URL ein, über die ein Konto gesucht werden soll, z. B. https://YOUR_ESPO_DOMAIN/api/v1/Case.
  4. Wählen Sie für Methode die Option GET aus.

  5. So konfigurieren Sie Anfrageparameter:

    1. So konfigurieren Sie den ersten Anfrageparameter:
      1. Klicken Sie unter Anfrageparameter auf Feld hinzufügen. Das Dialogfeld Feld hinzufügen wird angezeigt.
      2. Geben Sie im Feld Feldschlüssel den Wert where[0][attribute] ein.
      3. Geben Sie im Feld Feldwert den Wert contactId ein.
      4. Klicken Sie auf Speichern.

    2. Wiederholen Sie den vorherigen Schritt, um die restlichen Anfrageparameter zu konfigurieren. Verwenden Sie dazu die Informationen in der folgenden Tabelle. Sie haben den ersten Anfrageparameter bereits erstellt.

      Feldschlüssel Feldwert
      where[0][attribute] contactId
      where[0][type] equals
      where[0][value] {ACCOUNT_ID}
      contactId {ACCOUNT_ID}
      sortBy createdAt
      asc false

  6. Geben Sie im Feld Speicherort der Antwortdaten den Wert data.list ein.

  7. Klicken Sie auf Speichern.

  8. Klicken Sie auf Return to developer settings (Zu Entwicklereinstellungen zurückkehren), um zur Seite Developer Settings (Entwicklereinstellungen) zurückzukehren.

Endpunkt zum Suchen eines Datensatzes nach ID konfigurieren

Wird häufig bei SDK-basierten Interaktionen verwendet. Damit können Sie eine bestimmte Datensatz-ID übergeben, um die Interaktion damit zu verknüpfen. So konfigurieren Sie den Endpunkt zum Suchen eines Datensatzes nach ID:

  1. Rufen Sie im Bereich CRM den Abschnitt API-Datensatz auf.
  2. Klicken Sie für den Endpunkt zum Suchen eines Datensatzes nach ID auf Einrichten. Die Seite Generic API Endpoint Setup (Einrichtung des generischen API-Endpunkts) wird angezeigt.
  3. Geben Sie im Feld URL die URL ein, über die ein Konto gesucht werden soll, z. B. https://YOUR_ESPO_DOMAIN/api/v1/Case/{RECORD_ID}.
  4. Wählen Sie für Methode die Option GET aus.
  5. Geben Sie im Feld Speicherort der Antwortdaten den Wert data ein.
  6. Klicken Sie auf Speichern.
  7. Klicken Sie auf Return to developer settings (Zu Entwicklereinstellungen zurückkehren), um zur Seite Developer Settings (Entwicklereinstellungen) zurückzukehren.

Endpunkt „Datensatz erstellen“ konfigurieren

So konfigurieren Sie den Create a record endpoint:

  1. Rufen Sie im Bereich CRM den Abschnitt API-Datensatz auf.
  2. Klicken Sie für Create a record endpoint (Einen Datensatzendpunkt erstellen) auf Setup (Einrichtung). Die Seite Generic API Endpoint Setup (Einrichtung des generischen API-Endpunkts) wird angezeigt.
  3. Geben Sie im Feld URL die URL ein, über die ein Konto gesucht werden soll, z. B. https://YOUR_ESPO_DOMAIN/api/v1/Case.
  4. Wählen Sie für Methode die Option POST aus.

  5. So konfigurieren Sie Anfrageparameter:

    1. So konfigurieren Sie den ersten Anfrageparameter:
      1. Klicken Sie unter Anfrageparameter auf Feld hinzufügen. Das Dialogfeld Feld hinzufügen wird angezeigt.
      2. Geben Sie im Feld Feldschlüssel den Wert description ein.
      3. Geben Sie im Feld Feldwert den Wert CALL Session:{CALL_ID} ein.
      4. Klicken Sie auf Speichern.

    2. Wiederholen Sie den vorherigen Schritt, um die restlichen Anfrageparameter zu konfigurieren. Verwenden Sie dazu die Informationen in der folgenden Tabelle. Sie haben den ersten Anfrageparameter bereits erstellt.

      Parameterschlüssel Parameterwert
      description Call Session: {CALL_ID}
      name Inbound Call from {ANI}
      contactId {ACCOUNT_ID}
      status New
      cchatId {CHAT_ID}
      ccallId {CALL_ID}
      cChannel {CHANNEL}
      Type {SESSION_TYPE}

  6. Geben Sie im Feld Speicherort der Antwortdaten den Wert data ein.

  7. Geben Sie im Feld Speicherort der Objekt-ID den Wert id ein.

  8. Klicken Sie auf Speichern.

  9. Klicken Sie auf Return to developer settings (Zu Entwicklereinstellungen zurückkehren), um zur Seite Developer Settings (Entwicklereinstellungen) zurückzukehren.

Endpunkt zum Aktualisieren eines Datensatzes konfigurieren

So konfigurieren Sie den Datensatz aktualisieren-Endpunkt:

  1. Rufen Sie im Bereich CRM den Abschnitt API-Datensatz auf.
  2. Klicken Sie für Endpunkt zum Aktualisieren eines Datensatzes auf Einrichtung. Die Seite Generic API Endpoint Setup (Einrichtung des generischen API-Endpunkts) wird angezeigt.
  3. Geben Sie im Feld URL die URL ein, über die ein Konto gesucht werden soll, z. B. https://YOUR_ESPO_DOMAIN/api/v1/Case/{RECORD_ID}.
  4. Wählen Sie für Methode die Option PUT aus.

  5. So konfigurieren Sie Anfrageparameter:

    1. So konfigurieren Sie den ersten Anfrageparameter:
      1. Klicken Sie unter Anfrageparameter auf Feld hinzufügen. Das Dialogfeld Feld hinzufügen wird angezeigt.
      2. Geben Sie im Feld Feldschlüssel den Wert parentId ein.
      3. Geben Sie im Feld Feldwert den Wert {RECORD_ID} ein.
      4. Klicken Sie auf Speichern.

    2. Wiederholen Sie den vorherigen Schritt, um die restlichen Anfrageparameter zu konfigurieren. Verwenden Sie dazu die Informationen in der folgenden Tabelle. Sie haben den ersten Anfrageparameter bereits erstellt.

      Parameterschlüssel Parameterwert
      parentId {RECORD_ID}
      parentType Case
      status New
      description {TICKET_DESCRIPTION}

  6. Geben Sie im Feld Speicherort der Antwortdaten den Wert data ein.

  7. Klicken Sie auf Speichern.

  8. Klicken Sie auf Return to developer settings (Zu Entwicklereinstellungen zurückkehren), um zur Seite Developer Settings (Entwicklereinstellungen) zurückzukehren.