logo
Entwicklung
ÜbersichtEntwicklungsbereichArbeitsbereichAPI-ReferenzBewährte PraxisÄnderungsprotokoll
Suchen
Deutsch
Entwicklungsbereich / Agent / Integration / Zoho-Sales-IQ
Zoho Sales IQ
Zuletzt aktualisiert：in about 8 hours

Zoho Sales IQ

Sie können den Agenten-Dienst in Zoho Sales IQ integrieren und ermöglichen so Nutzer:innen von Zoho Sales IQ, direkt über Zoho Sales IQ mit dem Agenten zu kommunizieren.

Integration vorbereiten

Vor der Integration müssen Sie einige Parameter in Zoho konfigurieren, die während des Integrationsprozesses mit GPTBots benötigt werden.

Client-ID erstellen

  1. Melden Sie sich in der Zoho API-Konsole an.

    Hinweis: Wenn Ihr Konto nicht in der US-Region registriert ist, müssen Sie die Domain wechseln. Details finden Sie hier:

    Rechenzentrum Entwicklerkonsole
    US (Vereinigte Staaten) https://api-console.zoho.com/add
    EU (Europa) https://api-console.zoho.eu/add
    IN (Indien) http://api-console.zoho.in/add
    AU (Australien) http://api-console.zoho.com.au/add
    CN (China) http://api-console.zoho.com.cn/add
    JP (Japan) http://api-console.zoho.jp/add

  2. Falls Sie bereits eine verfügbare Anwendung haben, öffnen Sie die entsprechende Anwendung, klicken Sie auf „Client Secret“ und kopieren Sie die zugehörige Client-ID und das Client Secret. Beide werden in der GPTBots-Integrationskonfiguration benötigt.

    image-20250507153254209

  3. Falls Sie keine verfügbare Anwendung haben, klicken Sie oben rechts auf ADD CLIENT und erstellen Sie einen passenden Client entsprechend Ihrem Anwendungstyp.

    image-20250507153127149

    image-20250507153459912

  4. Wenn Sie eine neue Anwendung erstellen, geben Sie in der Homepage URL den aktuellen Domainnamen Ihres Services ein. Fügen Sie bei den Authorized Redirect URIs den Domainnamen Ihres Services gefolgt von /api/console/bot/zoho/salesiq/redirect ein und klicken Sie auf CREATE. Nach erfolgreicher Erstellung generiert das System eine Client-ID und ein Client Secret. Kopieren Sie beide, da sie in der GPTBots-Integrationskonfiguration benötigt werden.

    image-20250507160039517

Hinweis: Eine Client-ID kann maximal 20 gleichzeitig erfolgreiche Autorisierungen haben. Wird diese Anzahl überschritten, wird die Zoho-Autorisierung des zuerst autorisierten Agenten ungültig.

Integrationskonfiguration

  1. Melden Sie sich bei GPTBots an.

  2. Öffnen Sie Ihre Organisation, wählen Sie den gewünschten Agenten, speichern Sie die Version und klicken Sie auf Publish. Nach erfolgreicher Veröffentlichung klicken Sie auf Integrations.

    image-20250225121541516

  3. Wählen Sie als Integrationsmethode Zoho Sales IQ aus.

    image-20250507163753173

  4. Geben Sie die erforderlichen Parameter ein:

    • Client ID und Client Secret: Erforderlich, wurden bereits in der Vorbereitungsphase abgerufen;
    • Screen Name: Erforderlich, der Wert stammt aus der Seite Ihres angemeldeten Kontos. Verwenden Sie den ersten Pfad-String nach dem Domainnamen. Beispiel: In der Adresse https://salesiq.zoho.com/gptbos/mychats/000000000000003 ist der Screen Name „gptbots“;
    • Email: Erforderlich, die im Profil des Zoho-Kontos hinterlegte E-Mail-Adresse;
    • Server Region: Wählen Sie die Region Ihres Zoho-Kontos aus;
    • Public Key: Optional. Falls Sie in der späteren Webhook-Konfiguration „Secure your webhook“ aktivieren, klicken Sie zuerst auf Integration und kehren dann zurück, um den Schlüssel einzutragen. Andernfalls ist dieses Feld nicht erforderlich.

    image-20250507164140213

  5. Nach dem Klick auf Integration erscheint ein Pop-up zum Autorisierungsstatus. Klicken Sie dort bitte auf Accept.

    image-20250507165858728

  6. Nach erfolgreicher Autorisierung generiert GPTBots eine Webhook-URL. Wechseln Sie anschließend zur Seite Setting.

    image-20250507172323517

  7. Navigieren Sie nacheinander zu Workflows - Data Workflows und klicken Sie oben rechts auf Add (View).

    Hinweis: Bei einigen Kontoversionen heißt dieser Einstiegspunkt Webhooks - Data modifications; beide haben dieselbe Funktion.

    alt text

    alt text

    alt text

  8. Füllen Sie die Webhook-Daten aus:

    • Brand: Wählen Sie die Marke, die die Workflows (Webhooks) empfangen soll. Sie muss mit der Marke übereinstimmen, die die Besucher tatsächlich verwenden — also der Marke, zu der der auf Ihrer Website eingebettete Widget-Installationscode gehört. Wird hier die falsche Marke gewählt, lösen die Ereignisse dieser Konversation diesen Workflow nicht aus, und GPTBots erhält überhaupt keine Nachrichten.

    • Module: Wählen Sie Conversation.

    • URL to be invoked: Tragen Sie die aus der GPTBots-Integrationskonfiguration erhaltene Webhook-URL ein. Kopieren Sie sie direkt von der Integrationskonfigurationsseite und übernehmen Sie keine Adresse aus einer anderen Umgebung, sonst werden die Nachrichten an eine andere Umgebung gesendet.

    • Events: Sie müssen conversation.created und conversation.visitor.replied gleichzeitig aktivieren, keines darf fehlen:

      • conversation.created: Benachrichtigt GPTBots, wenn eine neue Konversation erstellt wird. Auf dieser Basis übernimmt (pick up) GPTBots die Konversation;
      • conversation.visitor.replied: Benachrichtigung für jede weitere Nachricht des Besuchers. Bei der Verarbeitung dieses Ereignisses prüft GPTBots die Zugehörigkeit der Konversation. Wurde die Übernahme mangels conversation.created nicht abgeschlossen, werden alle weiteren Nachrichten des Besuchers verworfen.

      Alle übrigen Ereignistypen werden von GPTBots nicht verarbeitet; ihre Aktivierung hat keine Wirkung.

    • Action: Wählen Sie Webhook.

    Klicken Sie nach dem Ausfüllen auf Create webhook.

    alt text

    ⚠️ Hinweis: Als Webhook URL muss hier die auf der Integrationskonfigurationsseite generierte Webhook-URL eingetragen werden. Sie ist nicht dieselbe Adresse wie die Callback-Adresse des Szenarios „Menschlicher Support - Other to Zoho Sales IQ“ (/api/console/human/callback/zoho/salesiq/event); beide dienen unterschiedlichen Zwecken, und eine Verwechslung führt dazu, dass Nachrichten verworfen werden. Wenn Sie beide Szenarien nutzen möchten, erstellen Sie bitte jeweils einen eigenen Data Workflow.

  9. Secure your webhook: Optionaler Schritt. Sie können wählen, ob die Sicherheit des Webhooks überprüft werden soll (ob die Anfrage von der offiziellen Quelle stammt und nicht gefälscht ist). Klicken Sie nach dem Aktivieren auf „Public Key generieren“, kopieren Sie den mit „In Use“ markierten Public Key und tragen Sie ihn auf der GPTBots-Integrationskonfigurationsseite ein.

    image-20250507173308438

Mit dem Agenten in Zoho Sales IQ kommunizieren

Nach erfolgreicher Integrationskonfiguration können Sie im Zoho-Service mit dem Agenten kommunizieren.
image-20250507182819135

Häufige Fragen

1. Konversation kann nicht erstellt werden, Meldung Live chat has been disabled

Wenn die Live-Chat-Funktion der entsprechenden Marke auf Zoho-Seite deaktiviert ist, verweigert Zoho die Erstellung der Konversation und gibt diesen Fehler zurück. Bitte prüfen Sie:

  1. Öffnen Sie Settings - Brands und stellen Sie sicher, dass der Status der Zielmarke Active ist (der Schalter ganz rechts in der Liste ist aktiviert). Ist eine Marke deaktiviert, können unter ihr keinerlei Konversationen erstellt werden;
  2. Öffnen Sie für diese Marke Configurations - Channels und stellen Sie sicher, dass der Schalter Live chat aktiviert ist;
  3. Stellen Sie sicher, dass die gewählte Abteilung (Department) nicht deaktiviert ist.

Wenn Sie in den Configurations keinen Live-chat-Schalter finden, ist diese Funktion in der Regel auf Ebene des Zoho-Kontotarifs deaktiviert. Wenden Sie sich in diesem Fall an den offiziellen Zoho-Support.

2. Nachrichten aus dem Zoho-Widget kommen im Zoho-Servicedesk an, aber der Agent antwortet überhaupt nicht

Zunächst eine wichtige Grundlage: Nach dem Empfang des Zoho-Webhooks gibt GPTBots sofort eine Erfolgsantwort zurück und verarbeitet die Nachricht anschließend asynchron. Selbst wenn eine Nachricht auf GPTBots-Seite verworfen wird, bleibt in der Data-Workflows-Liste von Zoho der Wert Failures daher 0 — Failures eignet sich nicht zur Fehlerdiagnose. Das einzig verlässliche Kriterium ist die Spalte Last Triggered.

Schritt 1: Mit Last Triggered eingrenzen, auf welcher Seite das Problem liegt

Öffnen Sie Settings - Workflows - Data Workflows, suchen Sie den Eintrag, der auf die Integrations-Webhook-URL zeigt, und prüfen Sie Last Triggered. Beachten Sie, dass diese Spalte die Zeit in der Zeitzone des Zoho-Kontos anzeigt, die um mehrere Stunden von Ihrer lokalen Zeit abweichen kann. Rechnen Sie sie daher vor dem Vergleich um.

  • Leer oder nicht der Zeitpunkt Ihrer soeben gesendeten Nachricht → Zoho hat gar keine Anfrage gesendet, das Problem liegt auf Zoho-Seite (siehe A unten);
  • Genau der Zeitpunkt der soeben gesendeten Nachricht → Die Anfrage wurde gesendet, das Problem liegt in den Verarbeitungsbedingungen auf GPTBots-Seite (siehe B unten).

A. Zoho-Seite: Der Workflow wurde nicht ausgelöst

  1. Der Schalter ganz rechts an diesem Workflow steht auf ENABLED (grün);

  2. Brands enthält die Marke, die die Besucher tatsächlich verwenden — öffnen Sie die betreffende Konversation; oben auf der Detailseite der Konversation sehen Sie den zugehörigen Markennamen, den Sie zum Abgleich verwenden können. Dies ist die häufigste Ursache: Das Widget gehört zu Marke A, der Workflow ist aber an Marke B gebunden, sodass das Ereignis niemals ausgelöst wird;

  3. Module ist Conversation;

  4. Events enthält sowohl conversation.created als auch conversation.visitor.replied.

    Hinweis: Der Workflow des Szenarios „Menschlicher Support - Other to Zoho Sales IQ“ verwendet conversation.operator.replied / conversation.completed; Besuchernachrichten lösen ihn nicht aus. Das Vorhandensein jenes Workflows bedeutet nicht, dass das Integrationsszenario funktioniert — beide Szenarien benötigen jeweils einen eigenen Workflow.

B. GPTBots-Seite: Anfrage empfangen, aber verworfen

  1. URL des falschen Szenarios verwendet: Das Integrationsszenario nutzt /api/console/bot/integration/chat/zoho/salesiq/{clientId}, das Szenario „Menschlicher Support“ nutzt /api/console/human/callback/zoho/salesiq/event. Bei Vertauschung wird die Nachricht mangels passender Konfiguration verworfen, während Zoho weiterhin Erfolg anzeigt;
  2. URL zeigt auf eine andere Umgebung: Stellen Sie sicher, dass die Domain mit der aktuell von Ihnen genutzten Umgebung übereinstimmt;
  3. „Secure your webhook“ aktiviert, aber kein Public Key eingetragen: Nach der Aktivierung signiert Zoho jeden Callback. Ist der Public Key auf GPTBots-Seite leer, schlägt die Prüfung zwangsläufig fehl und die Anfrage wird verworfen. In der Debugging-Phase empfiehlt es sich, diese Option zunächst zu deaktivieren;
  4. Agent nicht veröffentlicht: Der Integrationskanal liest die veröffentlichte Version. Wurde für den Agenten nie eine Version veröffentlicht, werden Nachrichten verworfen. Speichern Sie zuerst eine Version und klicken Sie auf Publish;
  5. Konversation von einem anderen Agenten (Mitarbeiter) übernommen: Das Integrationsszenario setzt voraus, dass die Konversation dem Zoho-Konto der in der Integrationskonfiguration eingetragenen Email gehört. Wird die Konversation von einem anderen Mitarbeiter manuell übernommen, werden weitere Besuchernachrichten nicht mehr an den Agenten weitergeleitet;
  6. Autorisierung abgelaufen: Prüfen Sie auf der GPTBots-Integrationskonfigurationsseite, ob der Autorisierungsstatus in Ordnung ist. Wenn dieselbe Client-ID mehr als 20-mal erfolgreich autorisiert wurde, verliert der zuerst autorisierte Agent seine Autorisierung (siehe Hinweis oben) und muss neu autorisiert werden.

3. Zoho empfängt die Nachrichten, aber Antworten des menschlichen Supports kommen nicht zurück

Dies ist das typische Phänomen einer „Einweg-Kommunikation“; die Ursache ist ein nicht wirksamer Webhook. Bitte prüfen Sie:

  1. Öffnen Sie Settings - Workflows - Data Workflows und stellen Sie sicher, dass der entsprechende Workflow den Status ENABLED hat;
  2. Stellen Sie sicher, dass die im Workflow gewählten Brands mit der tatsächlich verwendeten Marke übereinstimmen;
  3. Stellen Sie sicher, dass bei Events die erforderlichen Ereignisse aktiviert sind und die URL die Adresse des passenden Szenarios ist (die Adressen des Integrationsszenarios und des Szenarios „Menschlicher Support“ unterscheiden sich, siehe den Hinweis in Schritt 8 oben);
  4. Prüfen Sie die Spalte Last Triggered in der Liste. Bleibt sie leer oder passt die Zeit nicht zu dieser Konversation, wurde das Ereignis nie ausgelöst — prüfen Sie dann die obige Konfiguration erneut. Die Spalte Failures ist kein gültiges Kriterium (Begründung siehe vorherige häufige Frage).

4. Callback schlägt nach Aktivierung von Secure your webhook fehl

Nach Aktivierung dieser Option fügt Zoho jedem Callback eine Signatur hinzu. Ist auf GPTBots-Seite der zugehörige Public Key nicht eingetragen, schlägt die Signaturprüfung fehl und die Anfrage wird abgelehnt. Kopieren Sie den in Zoho mit In Use markierten Public Key auf die GPTBots-Integrationskonfigurationsseite. In der Debugging-Phase können Sie die Option auch zunächst deaktivieren, um die Verbindung zu testen.