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
Pedro Rodrigues
This is awesome Aimee Spanier! Will it be possible to request information from the user in order to use their input as parameters in API request (e.g. validate email address on external CRM)?
5
Chris Tomkins
Yes Pedro Rodrigues - this is on the roadmap to be delivered in the next few months.
1
Pedro Rodrigues
Awesome, thanks for the follow up!
0
Jason Walker-C
This is great. Can we use this to get info from our own ZD instance? I would love to get messaging ticket count and display that to customers. This would help set wait time expectations since we can't do that natively. I tried but keep getting unauthorized 401 errors. I also tried setting the user and pwd - key and value.
1
Eduardo
Hi @Jason , at the moment it is not possible to collect this information, as we were not able to use the parameters of the other requests to use in the new request.
Follow the example images
I saved the userid as a variable, and I can't use this variable in another API call like this.
![](/hc/user_images/sV70ofXwYOvm4F7AmhHXwQ.png)
And for your 401 error, you need to create a global token or use a Base64 token with your username and password, and you need to enable that within Zendesk.
You can follow this instruction https://developer.zendesk.com/api-reference/ticketing/introduction/#security-and-authentication
1
okean123
Hey there! I am currently working on including an external API into our bot. I am trying to do a POST request, but having troubles with the request body.
The format that I enter for the request body is normal JSON, like for example
{"test": "hello"}
Now the problem I encounter is that the external API that I use is returning that the request is invalid. When sending the exactly same request manually (for example through a browser console) the request is being processed correctly.
So my question is, do I have to format the JSON body in any specific way for Zendesk to correctly forward the request to the external API?
I have checked the Integration logs and it appears that the request body is being sent to the Zendesk servers as a string. Is it possible that when parsing the JSON string later into JSON some error occurs on your side?
The above seems like what is happening here to me, because when I checked the logs of one of our APIs that I tried to call using the tool, the request body contains not the actual JSON, but a stringified version of the JSON (with escaped quotation marks).
Any thoughts?
0
Eric Nelson
Can you provide us a code snippet of the request so we can take a look?
Thanks!
0
Edu Barros
How can I do API Call with database json And redirect to a específic group?
0
okean123
Eric Nelson
Sorry for the late response, but let me give you an example. In this example I am calling an API hosted on AWS, I will share the request logs to demonstrate the problem.
Let's start with the Zendesk request. This is what I put in Zendesk (Note that I added all implicitly required headers, they are just not in the screenshot and they are not relevant for the problem)
The above request leads to this being logged in our API:
You can see that the quotes are double escaped. Also I am not exactly sure where that \n at the end is coming from, I don't think I have entered a new line, but it's probably not relevant anyway.
Now when I send a request using Javascript directly the outcome is different. A request example:
This yields the following logs:
Here it just logs the JSON as a string, the way it was sent. This is also what is expected and correct.
So my question would be, am I using the API call in the flow builer wrong and the JSON should be entered in a different format? Or is there a problem in the software that breaks the JSON when sending the HTTP requests?
Please let me know if you have any other questions about the example I provided.
2
Henry Kremer
Hi there,
How can we pass variables stored in the chat to an API request URL?
For example, is it possible to store the customer question as a variable to pass as a param in the URL?
Thank you in advance
2
Shayan Moussawi
Unfortunately there currently is a bug where we stored variables are not translated when used in text.
This is quite detrimental to the end user experience.
0
Raphaël Péguet - Officers.fr
Hi Zendesk team,
Can you add the info:
- how to make API calls to the Zendesk instance to :
1- get info
2- do updates on the ticket?
- what should we put as key and value to be able to connect to our proper Zendesk Instance?
Thank you
0
Nara
0
Diego Villarreal
We're trying to use a GET call to an endpoint on our server that receives a user's e-mail and returns a json with several data points about our user. However, as we try and test it out, we get an error saying that the API call can't include a period so sending an email as a variable in the call doesn't seem to work.
0
Tipene Hughes
Can you provide an example of the endpoint URL you're making the request to, including any query parameters (being sure to redact any sensitive info). Also, could you include the full error you're seeing when making the request.
Thanks!
Tipene
0
Diego Villarreal
Hi Tipene, certainly, here are the steps to reproduce, in Bot Flow Builder:
- Add Step
- Make API Call
- In API Details, include GET Request Method with this type of request https://XXXXXXX.XXXXX.XXXXX/api/admin/users/{{sf.requester.email}}/
- Select Add Variable and select Responses from Customers: Email, which adds {{sf.requester.email}} as displayed above
- Press Make API Call and then are asked to include Test Data in the email. I put in my email XXXXXX@gmail.com and get an error "Variables added in the URL path must not contain periods."
0
Tipene Hughes
Thanks for providing this clarification for me!
Unfortunately the error that you're seeing is a result of having a period in the variable, as you mentioned in your earlier comment. This is a system rule and can't be overwritten. Variables with additional symbols or punctuation should be sent as a payload body in a PUT or POST request.
Feel free to reach out with any questions!
Tipene
0
Gabriele Sannicandro - EXT
Hello
I have a problem with the headers keys: i need to use "authorization" key with a bearer token, but the field value it's short!
So my bearer token was truncate and i have an authorization error....
0
Tipene Hughes
Thanks for reaching out!
The character limit for the value field is 256 including spaces. Generally, you shouldn't see oAuth tokens exceeding that length. Can you make sure there are no extra spaces in the value field that might be causing the issue?
Thanks!
Tipene
0
Gabriele Sannicandro - EXT
My web service use JWT token leght 372 c.
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoicGFwZXJpbm8iLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL2V4cGlyYXRpb24iOiIwMi8wNi8yMDI2IDEzOjU5OjM1IiwiZXhwIjoxNzgwNDA4Nzc1LCJpc3MiOiJJc3N1ZXIiLCJhdWQiOiJBdWRpZW5jZSJ9.VG7qHYzzojd2HwVteMrm4gDOFN8KGUsP2F24DtTgX7E"
There are many web service with long token...
0
Shiyu Zhu
Hey okean123
Thanks for the feedback. The issue has been fixed and it would be great if you can confirm.
0
Diego Villarreal
Hi Tipene Hughes - we noticed that we can send a payload body with POSTs but not with GET requests. Is it possible to enable us to send a payload in a GET? That would solve our problem of not letting us include e-mails in the URL of the original GET request but rather in the body.
0
Shiyu Zhu
Hey Gabriele Sannicandro - EXT
Thanks, I have captured your feedback for us to fix.
1
Tipene Hughes
Hi Diego Villarreal,
Unfortunately it isn't possible to send data as a payload via a GET request; you will need to use the appropriate POST or PUT request method.
I've logged this as feedback to our product team who may look at adding this as additional functionality in future updates depending on demand.
Sorry I couldn't be more help!
Tipene
0
Gauri Sanil
Is there a way to send the current user context to the make an api call step with the help of a variable ? I want to present a different flow for authenticated versus anonymous users in flow builder...can you let me know the details ?
1
Shiyu Zhu
Hey Gauri Sanil
This is not possible but this use case has been prioritized on our roadmap to solve for H1, 2023. Thanks
0
Carlton
Is it possible to access the external_id value of the user?
0
Shiyu Zhu
We are planning to expose external_id as a system variable in Q1,2023.
0
Carlton
Is there any variable we can use to identify the user other than external_id? Such as a ZenDesk ID we could sync to our db
1
Kirk
Hi @... also curious about Carlton's question if you have any thoughts. How can we insert variables that are customer-specific via an API call with FlowBuilder?
0