Verwenden des Schritts „API-Aufruf durchführen“ in einem AI Agent für Messaging (Legacy)

Welchen Plan habe ich

Suite

Team, Growth, Professional, Enterprise oder Enterprise Plus

In diesem Beitrag werden Funktionen beschrieben, die nur Kunden zur Verfügung stehen, die seit dem 2. Februar 2025 einen AI Agent entworfen oder veröffentlicht haben. Weitere Informationen zu den entsprechenden Funktionen im Add-on „AI Agents – Advanced“ finden Sie unter Integrieren anderer Plattformen mit AI Agents – Advanced.

Mit dem Schritt API-Aufruf durchführen können Sie einen API-Aufruf an ein internes CRM- oder ERP-System o. ä. konfigurieren oder Details zur Konversation an einen externen Endpunkt wie Amazon Event Bridge oder Google Analytics übertragen.

In diesem Beitrag erfahren Sie, wie Sie diesen Schritt in einen AI Agent für Messaging einbinden und konfigurieren.

Allgemeine Informationen zum Schritt API-Aufruf durchführen und den entsprechenden Konfigurationsregeln finden Sie im Beitrag Überblick über die Schrittarten für AI Agents: API-Aufruf durchführen.

Dieser Beitrag enthält die folgenden Abschnitte:

• Hinzufügen des Schritts „API-Aufruf durchführen“ zu einem AI Agent
• Hinzufügen von API-Details
• Speichern von Variablen aus der API-Antwort
• Überblick über die Schrittverzweigungen

Hinzufügen des Schritts „API-Aufruf durchführen“ zu einem AI Agent

Um den Schritt API-Aufruf durchführen zu einem AI Agent hinzuzufügen, sind mehrere Aufgaben erforderlich.

Bei den unten stehenden Anweisungen wird vorausgesetzt, dass Sie bereits einen AI Agent für Messaging erstellt haben, zu dem Sie diesen Schritt hinzufügen möchten.

Hinweis: Wenn das angerufene System nicht innerhalb von 10 Sekunden antwortet, wird der Anruf wegen Zeitüberschreitung abgebrochen.

So fügen Sie den Schritt „API-Aufruf durchführen“ hinzu

1. Klicken Sie in der Seitenleiste des Admin Centers auf KI und dann auf AI Agents > AI Agents.
2. Klicken Sie auf AI Agents für Messaging verwalten.
3. Klicken Sie auf den Namen des AI Agent, den Sie bearbeiten möchten.
4. Klicken Sie auf die Registerkarte Antworten und erstellen Sie eine neue Antwort bzw. öffnen Sie eine vorhandene Antwort.
5. Klicken Sie im Bot-Builder an der Stelle, an der Sie den Schritt einfügen möchten, auf das Symbol Schritt hinzufügen: entweder am Ende einer Verzweigung oder zwischen zwei vorhandenen Schritten.
6. Klicken Sie im Konfigurationsfenster auf API-Aufruf durchführen.
7. Geben Sie aussagekräftige Informationen zu diesem Schritt ein.
   • Name: Ein Name, an dem Ihr Team den Aufruf leicht erkennt.
   • Beschreibung (optional): Eine kurze Beschreibung der durch den Anruf ausgelösten Aktion.

   Diese Informationen sind für Kunden nicht sichtbar.

8. Fahren Sie wie unter Hinzufügen von API-Details beschrieben fort.

Hinzufügen von API-Details

Konfigurieren Sie im Abschnitt „API-Details“ den gewünschten HTTP-Aufruf, indem Sie die HTTP-Anfragemethode und den Standort der externen Ressource angeben sowie bei Bedarf weitere Header hinzufügen. Die folgenden Schritte sind eine Fortsetzung des im vorherigen Abschnitt beschriebenen Verfahrens.

So fügen Sie die API-Details hinzu

1. Klicken Sie im Konfigurationsfenster auf API-Details.
2. Wählen Sie eine Anfragemethode:
   • GET ruft eine externe Ressource vom API-Service ab. Dies ist die am häufigsten verwendete Methode.
   • POST sendet Daten, um eine Ressource in einem externen System zu erstellen. Wenn die Ressource bereits vorhanden ist, wird sie durch die gesendeten Daten geändert.
   • PUT sendet Daten, um eine Ressource zu aktualisieren.
   • PATCH sendet Daten, um eine Ressource an einem externen Standort zu aktualisieren. Mit dieser Methode werden Teile der Ressource verändert.
   • DELETE entfernt die Ressource am externen Standort.
3. Geben Sie eine Endpunkt-URL ein.

   Die Endpunkt-URL ist der Standort der externen Ressource, zu der eine Verbindung hergestellt werden soll. Die Endpunkt-URL unterstützt das https://-Protokoll. Sie können Variablen in den Pfad oder in die Query-Zeichenfolge einer URL einfügen. Weitere Informationen finden Sie unter Übergeben von Variablen in einem API-Aufruf.

4. Wählen Sie optional eine Verbindung zur Authentifizierung des API-Aufrufs.
   Hinweis: Sie müssen eine Verbindung erstellen, bevor Sie sie im Schritt API-Aufruf durchführen verwenden können.
5. Geben Sie bei Bedarf den Schlüssel und den Wert für einen optionalen Header ein.
   Wichtig: Verwenden Sie für Authentifizierungstypen keine HTTP-Header, sondern stattdessen API-Verbindungen.

   Wenn der Schritt API-Aufruf durchführen authentifizierungsbezogene Header wie authorization oder x-api-key enthält, schlägt er automatisch fehl. Wenn ein Schritt API-Aufruf durchführen fehlschlägt, folgt die Konversation den Schritten der Verzweigung API-Aufruf fehlgeschlagen.

6. Klicken Sie auf API-Aufruf durchführen, um den API-Aufruf zu testen.

   Wenn zur URL oder zum Header des Schritts Variablen hinzugefügt werden, können Sie optionale Testdaten für Ihren externen Service eingeben, um zu prüfen, ob der API-Aufruf wie erwartet funktioniert. Beachten Sie, dass hierbei eine HTTP-Anfrage an die konfigurierte Endpunkt-URL gesendet wird.

Übergeben von Variablen in einem API-Aufruf

Wenn Sie eine Endpunkt-URL für einen API-Aufruf eingeben, können Sie Variablen in den Pfad oder die Query-String einer URs einfügen. Damit können Sie Daten aus der Konversation an das externe System weitergeben.

So kann ein AI Agent für Messaging einen Kunden beispielsweise mit dem Schritt Details anfordern auffordern, eine Bestellnummer einzugeben. Der AI Agent kann dann über den Schritt API-Aufruf durchführen den Versandstatus für die Bestellung aus Ihrem Online-Shop abrufen.

Sie können keine Variablen in der Domäne oder Subdomäne einer Endpunkt-URL verwenden. Die folgende Tabelle enthält Beispiele für gültige und ungültige Werte für die Endpunkt-URL.

Gültige Endpunkt-URL	Ungültige Endpunkt-URL
https://myshopify.com/admin/api/orders/order_number.json Eine Bestellung anhand der Bestellnummer aus Shopify abrufen.	https://domain.com/api/search?input=value Variablen können nicht zur Domäne/Subdomäne hinzugefügt werden
https://maps.googleapis.com/maps/api/place?input=city_name Einen Ort per Schlüsselwortsuche aus der Google Places API abrufen.	https://example.com/api/search?key=value Variablen können nicht zum Query-Stringschlüssel hinzugefügt werden.

Wenn eine Variable ungültig oder leer ist, überspringt der AI Agent die Variable während einer Konversation.

Hinweis: Variablenwerte werden nicht automatisch übersetzt. Denken Sie daran, wenn Sie in Ihren Messaging-Konversationen automatische Übersetzung verwenden.

Speichern von Variablen aus der API-Antwort

Nachdem Sie die Details konfiguriert und den API-Aufruf getestet haben, können Sie die Werte aus der JSON-Antwort des API-Aufrufs als Variablen speichern. Im Schritt API-Aufruf durchführen können Sie bis zu 12 Variablen speichern. Es werden nur die ersten 280 Zeichen eines Variablenwerts gespeichert.

So erstellen Sie eine Variable anhand der Antwortdaten

1. Klicken Sie im Konfigurationsfenster auf API-Aufruf durchführen.
2. Erweitern Sie das Akkordeon und identifizieren Sie die Daten aus dem externen System, die Sie in eine Variable umwandeln möchten.
   Tipp: Die vom externen System zurückgegebene Rohdatenantwort können Sie in der Registerkarte „Antworttext“ einsehen.
3. Klicken Sie auf Speichern.
4. Legen Sie einen Namen für die neue Variable fest.

   Variablennamen dürfen nur Kleinbuchstaben, Ziffern und Unterstriche enthalten.

Übergeben von Array-Variablen in einem API-Aufruf

Sie können Variablen an das externe System übergeben, indem Sie API-Aufruf durchführen verwenden und eine URL angeben. Das externe System muss über einen API-Endpunkt verfügen. Ein API-Endpunkt ist eine URL, über die die API Anfragen erhält und Antworten sendet, sodass zwei Systeme miteinander interagieren können. Antworten werden wie im folgenden Beispiel dargestellt im JSON-Format (JavaScript Object Notation) generiert.

{               
    "info": {   
        "count": 50,
        "pages": 2,
        "next": "https://mycompany.com/api/orders?page=2",
        "prev": null
    },      
    "results": [
        {   
            "id": 1052,
            "name": "Alexander Cummings",
            “address”: “123 MyStreet”,
            "Item": "belt",
            "price": "15.00",
            "image": "https://mycompany.com/api/orders/avatar/1.jpeg",
	…
    

Im Admin Center werden nur die ersten Elemente der Array-Variablen angezeigt, damit erkennbar ist, welche Daten zurückgegeben werden. In der oben stehenden JSON-Ausgabe werden beispielsweise die Elemente id, name, address, item, price und image angezeigt. Diese Daten werden in der Regel an ein Karussell übergeben, in dem allerdings maximal 10 Elemente angezeigt werden können.

Hinweis: In der Antwort werden nur die ersten 280 Zeichen eines Eigenschaftswerts angezeigt.

Verschachtelte JSON-Arrays lassen sich auch als Array-Variablen speichern. Im Fall der folgenden JSON-Ausgabe können beispielsweise lastname und firstname als separate Array-Variablen gespeichert werden.

"name": 
   {
      "lastname": "Cummings”,
      "firstname": “Alexander"
   },
    

Sie können das Array oder die Array-Werte nicht in der Karussellkonfiguration im Admin Center bearbeiten. Wenn Sie Daten ändern möchten, müssen Sie das Array im Admin Center löschen und ein neues Array erstellen.

Wenn die zurückgegebene Variable null ist, wird das Element im Karussell nicht angezeigt. Nehmen wir beispielsweise an, dass der Wert der Variablen {{customer.order}} im folgenden Szenario leer ist. In diesem Fall wird Karte 1 mit dem Teiltitel „Order number“ dargestellt. Der Titel von Karte 2 ist leer, weshalb Karte 2 nicht angezeigt wird.

Card 1
Title: Order number {{customer.order}}
Description: Here's your order {{product.description}}

Card 2
Title: {{customer.order}}
Description: Here's your order {{product.description}}
    

Beispiel

In diesem Beispiel wird eine Array-Variable mit einem API-Endpunkt erstellt, die ein Array von Bestellungen zurückgibt. Das Array „orders“ wird durch die Eigenschaft „results“ im folgenden API-Antwort-Snippet spezifiziert.

     {
  "info": {
   "count": 5,
   "pages": 1
  },
  "results": [
   {
    "createdAt": "July 10, 2023",
    "name": "Connie Stokes",
    "Shippingaddress": "123 Street, City, State",
    "order": {
      "Status": "Ordered",
      "Image": "https://images.pexels.com/photos/1484808/pexels-photo-1484808.jpeg"
    },
    "Quantity": 1,
    "Price": 45,
    "Item": "Shirt",
    "id": "1"
   },
…   

In diesem Beispiel wird API-Aufruf durchführen verwendet, um die Array-Variable zu erstellen, und dann ein dynamisches Karussell, um die Ergebnisse einem Endbenutzer anzuzeigen.

So erstellen Sie das Array

1. Klicken Sie im Konfigurationsfenster auf API-Aufruf durchführen.
2. Geben Sie als Namen orders ein.
3. Klicken Sie im Konfigurationsfenster auf API-Details.
4. Klicken Sie auf das Dropdownmenü Anfragemethode und dann auf GET.
5. Geben Sie die Endpunkt-URL ein.
6. Wählen Sie unter Authentifizierung Ihre Authentifizierungsmethode aus.

   Weitere Informationen finden Sie unter Erstellen von Verbindungen zur Integration mit externen Services.

7. Klicken Sie auf API-Aufruf durchführen.
8. Klicken Sie neben den Ergebnissen auf Speichern.

   

9. Klicken Sie im Pulldownmenü Wert auf Order und dann auf Image.

   Verwenden Sie den Standardvariablennamen („image“).

10. Klicken Sie auf Element hinzufügen und wiederholen Sie den obigen Schritt, um Elemente für Order Status und Element zu erstellen.

    Sie können bis zu 12 Elemente (oder Schlüssel-Wert-Paare) hinzufügen.

    

11. Klicken Sie auf Speichern.

So erstellen Sie das dynamische Karussell

1. Klicken Sie im Bot-Builder unter API-Aufruf erfolgreich auf Schritt hinzufügen und dann auf Karussell hinzufügen.
2. Klicken Sie im Konfigurationsfenster auf In dynamische Nachricht umwandeln.
3. Klicken Sie im Dropdownmenü Array auf results. Das ist das Array, das Sie oben erstellt haben.
4. Klicken Sie für den Titel auf das Pluszeichen und wählen Sie results.item.

   Sie können für den Titel und die Beschreibung bis zu 128 Zeichen eingeben.

5. Klicken Sie unter Button link auf das Pluszeichen und wählen Sie results.image.
6. Klicken Sie unter Button text auf das Pluszeichen und wählen Sie results.status.
7. Klicken Sie unter Image link auf das Pluszeichen und wählen Sie results.image.
8. Klicken Sie auf Fertig.

   

Hier ist ein Beispiel für ein dynamischen Karussell.

Überblick über die Schrittverzweigungen

Der Schritt API-Aufruf durchführen ist ein Verzweigungsschritt. Die weiteren Antworten des AI Agent hängen davon ab, ob die API-Anfrage erfolgreich ausgeführt wurde.

In den folgenden Fällen durchläuft der AI Agent die Verzweigung „Fehler“:

• Die API gibt den Antwortcode 400 oder 500 zurück.
• Eine der gespeicherten Variablen fehlt oder hat den Wert null.

In allen anderen Fällen durchläuft der AI Agent die Verzweigung „Erfolg“.

Durch Verwendung des Schritts API-Aufruf durchführen erkennen Sie an, dass das externe System, zu dem Sie eine Verbindung herstellen, laut dem Zendesk-Hauptdienstleistungsvertrag als Nicht-Zendesk-Dienst gilt. Die durch Verwendung der Bot-Builder-Erweiterungen aktivierten Nicht-Zendesk-Dienste werden nicht von Zendesk betrieben oder gesteuert. Zendesk übernimmt keine Verantwortung dafür, dass Sie oder die Nicht-Zendesk-Dienste die einschlägigen Gesetze oder Vorschriften einhalten.