In this article, we’ll walk you through the procedures involved in including and configuring the step in an AI agent for messaging.
For an overview of the Make API call step and its configuration rules, see Understanding AI agent step types: Make API call.
This article includes the following sections:
Adding a Make API call step to your AI agent
Adding the Make API call step to your AI agent includes a number of distinct tasks.
To add a Make API call step
- In Admin Center, click
Channels in the sidebar, then select AI agents and automation > AI agents.
- Click Manage AI agents for messaging.
- Click the name of the AI agent you want to edit.
- Click the Answers tab, then create a new answer or open an existing answer.
- In bot builder, click the Add step icon where you want to insert the step, either at the end of a branch, or between two existing steps.
- In the Configuration panel, click Make API call.
- Enter descriptive information for the step.
- Name: A name for the call that makes it easy for your team to identify.
- Description (optional): A short description of the action taken by the call.
This information will not be visible to customers.
- Continue with the procedure described in Adding API details.
Adding API details
Use the API details section to configure the HTTP call you want to make including the HTTP request method, location of the external resource, and adding headers if needed. The steps below are a continuation of the procedure in the previous section.
To add the API details
- In the Configuration panel, click API details.
- Select a Request method:
- GET retrieves an external resource from the API service. This is the most commonly used method.
- POST sends data to create a resource in an external system. If the resource already exists, the data sent modifies the resource.
- PUT sends data to update a resource.
- PATCH sends data to update a resource at an external site. It is used to apply partial modifications to the resource.
- DELETE removes the resource at the external location.
- Enter an Endpoint URL.
The endpoint URL is the location of the external resource you are connecting to. The endpoint URL supports the
https://
protocol. You can include variables in the URL's path or query string values. For more information, see Passing variables in an API call. - Optionally, select a connection to authenticate the API call.
Note: You must create a connection before using it in the Make API call step.
- If needed, enter the key and value for an optional header. Important: Don't use headers for authentication. Use API connections instead.
Make API call steps that include authentication-related headers, such as
authorization
orx-api-key
, automatically fail. If a Make API call step fails, the conversation follows the step's API call failed branch. - Click Make API Call to test the API call.
If variables are added to the step's URL or header, you can include optional test data to your external service to check if the API call is working as expected. Note this will make an HTTP request to the configured endpoint URL.
Passing variables in an API call
When you enter an Endpoint URL for an API call, you can include variables in the URL's path or query string values. This lets you pass data from the conversation to the external system.
For example, a messaging AI agent can prompt a customer to provide an order number using an Ask for details step. The AI agent can then use a Make API call step get the shipping status for the order from your online store.
You can't use variables in the domain or subdomain of an endpoint URL. The following table includes examples of valid and invalid Endpoint URL values.
Valid Endpoint URL | Invalid Endpoint URL |
---|---|
https://myshopify.com/admin/api/orders/order_number.json Retrieve an order by specifying the order ID from Shopify. ![]() |
Variables can’t be added to domain/subdomain |
Retrieve a location by keyword searches from Google’s places API. |
Variables can’t be added to query string key |
If a variable is invalid or empty, the AI agent skips the variable during a conversation.
Saving variables from the API response
After configuring details and testing the API call, you can save values from the API call's JSON response as variables. You can save up to 12 variables in a Make API call step. Only the first 280 characters of a variable's value are saved.
To create a variable from the Response data
- In the Configuration panel, click Make API call.
- Expand the accordion and identify the data from external system that you want to
turn into a variable.
Tip: Switch to the Response body tab to view the raw response that has came back from the external system.
- Click Save.
- Give the new variable a name.
Variable names must include only lowercase letters, numbers, and underscores.
Passing array variables in an API call
{
"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
, and
image
are
all displayed. This data is typically passed to a carousel, however the carousel can
display only up to 10 items.
lastname
and
firstname
can be saved as separate array
variables.
"name":
{
"lastname": "Cummings”,
"firstname": “Alexander"
},
You cannot edit the array or array values within the carousel configuration in Admin Center. If you need to change any data, you must delete the array in Admin Center and create a new one.
{{customer.order}}
is empty. For card 1, the card will be
rendered with a partial title of "Order number". For card 2, the resulting title is
empty so card 2 will not be rendered.
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}}
Example
{
"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"
},
…
This example uses Make API call to create the array variable and then uses a dynamic carousel to display the results to an end user.
To create the array
- In the Configuration panel, click Make API call.
- Enter orders for the name.
- In the Configuration panel, click API details.
- Click the Request method dropdown and select GET.
- Enter the URL for the Endpoint URL.
- For Authentication, select your authentication method.
For more information, see Creating connections to integrate with external services.
- Click Make API call.
- Click
Save
next to results.
- From the Value dropdown, select Order and then Image.
Use the default variable name (image).
- Click Add item and repeat the step above to create items for Order Status and
Item.
You can add up to 12 items (or key-value pairs).
- Click Save.
- In bot builder, click Add step under API call successful and select Add carousel.
- In the Configuration panel, click Convert to dynamic message.
- In the Array dropdown, click results. This is the array that you created above.
- For title, click the plus sign and select results.item.
You can enter up to 128 characters for the title and description.
- For Button link, click the plus sign and select results.image.
- For Button text, click the plus sign and select results.status.
- For Image link, click the plus sign and select results.image.
- Click Done.
Here's an example dynamic carousel.
About the step branches
The Make API call step is a branching step. Adding this step splits the AI agent responses depending on whether the API request was successfully executed.
- The API returns a 400 or 500 response code.
- The API returns a 200 response code where one of the saved variables is
missing or has a
null
value.
The AI agent will move down the success branch in all other cases.
64 comments
Raphaël Péguet - Officers.fr
What is the GET API request that we can make to know from the start (if the user is logged in) who he is and then use the info to speak with him or make API calls please
🙏🙏🙏
How come this is nowhere 😢😢😢
0
Tipene Hughes
Hey Raphaël Péguet - Officers.fr,
Here's a link which goes in to detail on how to identify end users through end-user authentication:
https://support.zendesk.com/hc/en-us/articles/4411666638746-Authenticating-end-users-in-messaging-for-the-Web-Widget-and-mobile-SDK
Let me know if this is what you're looking for, and if you have any questions!
Tipene
0
Raphaël Péguet - Officers.fr
Tipene Hughes thanks a lot for this, but my question was how to then use this info we got by authentification to make API calls in the flow builder like: search the requester e-mail address in shopify (just like we can do it if the requester fills a field during the flow builder).
When the requester fills the flow buiilder field we get a placeholder: {{sf.requester.email}} that we can use to make API calls.
I am wondering if this placeholder is usable if we authenticate user via the way you send
Best regards!
0
Leo Medalla
Is there a way for this to allow the bot to submit a request like a regular ticket?
0
Aron Diploma
Hi @..., any update with external_id?
0
Lisa Tam
Hi Aron Diploma, external_id is planned for end Q1 23 release.
Raphaël Péguet - Officers.fr, authenticated user email variable is also planned for end Q1 23 release
0
Gabriele Sannicandro
Hello .
In flow builder connect to my whatsapp number, How can send in an api call the whatsapp number of my requester?
0
Dane
As discussed on the ticket you have submitted, this option is not yet available.
0
Mgo Dono
Our user base is sorted based on the priority, can the API call check the priority of the user and direct them to a different bot flow, or block the contact live agent feature? (we let the urgent users to contact agents and for free users direct them to the center?)
0
Song Chen
I am currently working on including an external API(ChatGPT) into our bot. I am trying to do a POST request, but having "Request Taking Too Long" troubles .
Can I setting the time out boundary in Zendesk call API?
0
Shiyu Zhu
Hey Carlton Kirk,
Alongside with exposing external_id, we are also exposing end-users email and name, does those attributes help you at all in identifying the user?
0
Shiyu Zhu
Song Chen Our current timeline is 10 seconds and there is no ability to customize this right now.
Could you please elaborate what is the use case you are trying to achieve with ChatGPT? Thanks
0
John
Greetings, I have Shipstation App linked to Support. I would like to use the bot Flowbuilder to allow people to check the status of their order (shipped, accepted, tracking #, ec.)
Is this where I do it and how would I program it? Thanks for any help!
0
Dane
You can check the option in Using the Make API call step in Flow Builder. Please take note that customization is not part of Zendesk's scope.
The step above is only possible if Shipstation has API endpoints where you can make the calls.
0
John
Hi Dane,
The company sent me this link to everything, so I'm assuming I can do all of it? Would you mind seeing if it's possible?
https://www.shipstation.com/docs/api/orders/get-order/
0
Riat Abduramani
Hi,
I hope this message finds you well. I would like to address an issue regarding the current functionality of the Live Chat and Messaging tools. Previously, in Live Chat, we had the ability to set variables such as tags and custom fields before initiating a chat. This allowed us to enrich the ticket with relevant contextual data, such as order references, customer information, and the nature of the request through custom plugin apps.
However, with the introduction of the Messaging tool, we have noticed a limitation. The variables are now set from the Answer Bot and API call, and we are unable to set certain important information, such as the order reference, in the custom field. This means that we can only rely on the information provided by the customer, which can sometimes result in incorrect input.
To overcome this challenge, it would be extremely helpful for us to have the ability to set tags, variables, and custom fields once the ticket has been created, thereby obtaining the necessary context. It would be great if we could implement a similar functionality as shown below in the chat:
I hope this clarifies my requirement. Thank you for your attention to this matter.
Best regards,
0
Riat Abduramani
Hello,
I have a question: Have you considered incorporating variables into the ticket contexts? Currently, I don't see any provision for variables in the JSON payload `/api/v2/tickets/xxxxx.json`. Alternatively, it would be beneficial to use variables to populate custom fields.
Thank you.
0
Raphaël Péguet - Officers.fr
Hello
I saw while trying that when the flow builder API calls succeeds but finds an answer where ALL the saved variables are not present the flow builder takes the API failed path..
It's very unlogical :s
My use case is to use answer bot api into the flow builder. So i've saved as variables the url and the title of the 3 first articles. and every time the API calls finds 3 articles it works, but when it finds 1 or two articles the flow builder takes the "fail path"
0
Wes
Has something changed regarding saving array variables? Following along with the example in this article, the option to click "save" beside "results" isn't there. If you expand results you can save individual lines in that array, but there's no option to save the entire array.
0
Customer Support (admin)
Hi There,
After I created a button to save user's selected order, the button showed as "Option not supported" in my iOS app. Do you know what's the reason for this?
0
Dane
I have created a ticket for you to check your setup. Please wait for an update via email and let's continue from there.
0
Cody Hunter
Hello,
I have got to be making a simple mistake somewhere, but I am unable to figure out where. I have the content-type in and generated an admin API and I am getting errors each time. I have tried to change the URL endpoint and it has changed my error, but not really my results. At one point I managed to get json data over, but it was not the correct data, it was just form our home page. Could someone assist me with the steps to setting up the order API for Shopify in the Zendesk Conversation bot?
0
Tony
Did you have issues following the steps in the article? Also, if you are stuck, it might be good to reach out to our Support, explaining the errors you are getting.
Best,
0
Cody Hunter
Actually I figured out my issue. I was utilizing the order # and not the order id. Which brings me to my next question. How would a customer obtain an order id? I ask this because if the customer is unable to obtain this then this use case offers no value to customers in the chat, or am I incorrect on the customer's access to this number?
0
Maria Gmerek
Hi,
So would it be possible to make an API call via Magento and Zendesk integrations? Does the plug-in, give you the ability to retrieve data so that when a customer asks the chatbot about his order status, he can receive complete information about it (e.g. fulfillment status)?
0
Hiedi Kysther
Hi Maria Gmerek
Yes! As long as Magento have public API’s then our Make an API call step can make the HTTP requests to those systems.
Hope this helps!
1
דורין אברבך
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
Fatima Sbeih
Has anyone managed to set this up with Stripe?
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
이지훈(maclaude)
I have a similar question to Wes
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