Suite | Team, Growth, Professional, Enterprise oder Enterprise Plus |
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
Um den Schritt API-Aufruf durchführen zu einem AI Agent hinzuzufügen, sind mehrere Aufgaben erforderlich.
So fügen Sie den Schritt „API-Aufruf durchführen“ hinzu
- Klicken Sie in der Seitenleiste des Admin Centers auf
KI und dann auf AI Agents > AI Agents.
- Klicken Sie auf AI Agents für Messaging verwalten.
- Klicken Sie auf den Namen des AI Agent, den Sie bearbeiten möchten.
- Klicken Sie auf die Registerkarte Antworten und erstellen Sie eine neue Antwort bzw. öffnen Sie eine vorhandene Antwort.
- 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.
- Klicken Sie im Konfigurationsfenster auf API-Aufruf durchführen.
- 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.
- 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
- Klicken Sie im Konfigurationsfenster auf API-Details.
- 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.
- 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. - 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.
- 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
oderx-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. - 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. ![]() |
Variablen können nicht zur Domäne/Subdomäne hinzugefügt werden |
Einen Ort per Schlüsselwortsuche aus der Google Places API abrufen. |
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.
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
- Klicken Sie im Konfigurationsfenster auf API-Aufruf durchführen.
- 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.
- Klicken Sie auf Speichern.
- 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
{
"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",
…
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.
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.
{{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
{
"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
- Klicken Sie im Konfigurationsfenster auf API-Aufruf durchführen.
- Geben Sie als Namen orders ein.
- Klicken Sie im Konfigurationsfenster auf API-Details.
- Klicken Sie auf das Dropdownmenü Anfragemethode und dann auf GET.
- Geben Sie die Endpunkt-URL ein.
- Wählen Sie unter Authentifizierung Ihre Authentifizierungsmethode aus.
Weitere Informationen finden Sie unter Erstellen von Verbindungen zur Integration mit externen Services.
- Klicken Sie auf API-Aufruf durchführen.
- Klicken Sie neben den Ergebnissen auf Speichern.
- Klicken Sie im Pulldownmenü Wert auf Order und dann auf Image.
Verwenden Sie den Standardvariablennamen („image“).
- 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.
- Klicken Sie auf Speichern.
- Klicken Sie im Bot-Builder unter API-Aufruf erfolgreich auf Schritt hinzufügen und dann auf Karussell hinzufügen.
- Klicken Sie im Konfigurationsfenster auf In dynamische Nachricht umwandeln.
- Klicken Sie im Dropdownmenü Array auf results. Das ist das Array, das Sie oben erstellt haben.
- 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.
- Klicken Sie unter Button link auf das Pluszeichen und wählen Sie results.image.
- Klicken Sie unter Button text auf das Pluszeichen und wählen Sie results.status.
- Klicken Sie unter Image link auf das Pluszeichen und wählen Sie results.image.
- 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.
- 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“.
69 Kommentare
Alex Duffey
We need the character limit to be lifted. 280 is very small. Please look at opening this in the future. We are trying to a return an accessory list of products for one of our products, but the 280 limit stops us from providing that full list.
We tried breaking it up into multiple variables, but the the system requires us to save each one for each new product, which then runs into the 50 mac variable limit.
Please either raise the character limit to at least 1000 or raise the variable limit to at least 200.
0
Jeffrey Porter
Is it possible to include the originating URL for the page on which the chat bot was accessed in an API call? Our use case is that we are installing the chat bot on a video player and each video has a distinct URL. I created a chat bot flow that creates a Zendesk ticket. We'd like to be able to include the URL for the page in the ticket so we know where to go look for a problem. Right now we'd have to ask the user for something and we're guaranteed to get vague answers.
0
Aktie Projeto
Como faço para apagar variáveis que coloquei para teste e agora estão ocupando espaço no meu bot?
0
Yiannis Lamprou
I am trying to get data from hubspot via Make API call.
I am using POST method and i get all fields i want and can turn them to variable.
However the fields ( variables) are coming as numbers. (e.g
"hs_pipeline_stage":"67655766",
)How can i say to ZD to display text according to the variable coming in?
Is there a way to create an array or so besides carousel?
0
이지훈
I have a similar question to 6336142945306
For example, I want to use users.json to allow end users to retrieve their information using an API.
If a user has a "custom_role_id" value, I can create a flow by saving that value as a variable.
However, if the flow is executed for a user who does not have a "custom_role_id" value, an API error is returned.
In conclusion, even null values should be saved as variables, and when the variable is referenced in the flow, a null value should be returned instead of an error.
Is this possible?
0
Nir Tzezana
Hi,
I have some data I want to add to the API request body, this is data that I already have when the chat window opened (no need to gather it from the user), how can I do that?
0
Fatima Sbeih
Has anyone managed to set this up with Stripe?
0
דורין אברבך
Hey, https://support.zendesk.com/hc/en-us/articles/4572971586586/comments/4614301298458 is there any updates?
about getting information from the user in order to use their input as parameters in API request
0
Javier DM
Este caso que comentas, está justamente mencionado al pie de este artículo, donde pone:
He visto este tipo de situaciones, cuando se quiere utilizar un
null
value como expresión boolean. Por eso la llamada puede ser exitosa (respuesta 200), pero el valor no corresponde a ninguna de las varlables que se han guardado para el flujo, por lo que el paso API fallará.Un ejemplo:
En este caso, cuando el valor sea
null
el paso API va a fallar, por mas que la llamada sea exitosa. Ya que la variable aquí guardada esorganization_id
ynull
no es un valor exista para ese atributo.Espero esta explicación te sea de utilidad. Si precisaras revisar tu caso en mas profundidad, te sugiero por favor dirigirte a support.zendesk.com/hc e iniciar una conversación con el bot para ponerte en contacto con nuestro equipo de soporte.
Saludos y que tengas buena semana!
0
María del Mar Beiras Neira
Buenas, he configurado la respuesta de Hacer una llamada a una API al revisar los Logs, veo que la respuesta fue “SUCCEEDED”, sin embargo entra por la rama de error de llamada API, entonces realmente no se que hacer para este caso, ya que no entiendo porque esta entrando por esa rama.
0
Anmelden, um einen Kommentar zu hinterlassen.