Using the Make API call step in a conversation bot

Attention: Zendesk has renamed our bot capabilities. Answer Bot is now Zendesk bots, Flow Builder is bot builder, and Article Recommendations are autoreplies. Some older features still use the old terminology, which is reflected in the documentation. For more information on this change, see this announcement.

The Make API call step allows you to configure an API call out to another system, such as an internal CRM or ERP, or to push conversation details to an external endpoint, like Amazon Event Bridge or Google Analytics.

In this article, we’ll walk you through the procedures involved in including and configuring the step in a conversation bot.

For an overview of the Make API call step and its configuration rules, see Understanding bot step types: Make API call.

This article includes the following sections:

• Adding a Make API call step to your bot
• Adding API details
• Saving variables from the API response
• About the step branches

Adding a Make API call step to your bot

Adding the Make API call step to your bot includes a number of distinct tasks.

The procedures below assume you have already created a conversation bot, and are adding this step to that bot.

To add a Make API call step

1. Open the bot in bot builder.
2. Click the Add new icon where you want to insert the step, either at the end of a branch, or between two existing steps.
3. In the Configuration panel, click Make API call.
4. Enter descriptive information for the step. Note that this is visible to your team – customers will not see the information entered here:
   • 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.
5. Continue with the procedure described in Adding API details, below.

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

1. In the Configuration panel, click API details.
2. Use the dropdown to select a Request method:
   • GET retrieves data from a server at the external resource. This is the most commonly used method.
   • POST sends data to create or update a resource at an external system. If the resource already exists, the data sent modifies the resource.
   • PUT sends data to update or create a resource. If the resource already exists, the data sent replaces the 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.
3. Enter an Endpoint URL. The endpoint URL is the location of the external resource you are connecting to. The endpoint URL supports https:// protocol. You can include variables in the URL's path or query string values. For more information, see Using the Make API call step in a conversation bot.
4. Optionally, select a connection to authenticate the API call.
   Note: You must create a connection before using it in the Make API call step.
5. 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 an authentication-related header, such as authorization or x-api-key, automatically fail. If a Make API call step fails, the conversation follows the step's API call failed branch.

6. 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 bot can prompt a customer to provide an order number using an Ask for details step. The bot 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.	https://domain.com/api/search?input=value Variables can’t be added to domain/subdomain
https://maps.googleapis.com/maps/api/place?input=city_name Retrieve a location by keyword searches from Google’s places API.	https://example.com/api/search?key=value Variables can’t be added to query string key

If a variable is invalid or empty, the bot skips the variable during a conversation.

Note: Variable values are not auto-translated. Keep this in mind if you use automatic translation in your messaging conversations.

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.

Note: Only the first 280 characters of a variable's value appear in the response displayed in the messaging conversation.

To create a variable from the Response data

1. In the Configuration panel, click Make API call.
2. 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.
3. Click Save.
4. Give the new variable a name. Variable names must include only lowercase letters, numbers, and underscores.

Passing array variables in an API call

You can pass array variables using Make API call and providing a URL to the external system. The external system must have an API endpoint. An API endpoint is a URL where the API receives requests and sends responses, allowing two systems to interact. Responses are rendered in the JavaScript Object Notation (JSON) format, as shown in the following example.

{               
    "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",
	…

Only the first items in the array variable are displayed in Admin Center to help visualize what data is returned. For example, in the above JSON output, 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.

Note: Only the first 280 characters of a property value appear in the response.

Nested JSON arrays can also be saved as array variables. For example, given the following JSON output, 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.

If the returned variable is null, the item is not displayed in the carousel. For example, in the following scenario, suppose the value of the variable {{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

In this example, we’ll create an array variable using a test account endpoint (https://run.mocky.io/v3/b6c6180b-924c-407f-852d-9887d9a1641e). Here’s a snippet of the endpoint.

{
  "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"
   },
…

We’ll use Make API call to create the array variable and then use a dynamic carousel to display the results to an end user.

To create the array

1. In the Configuration panel, click Make API call.
2. Enter orders for the name.
3. In the Configuration panel, click API details.
4. If not already selected, click the Request method dropdown and select GET.
5. Enter https://run.mocky.io/v3/b6c6180b-924c-407f-852d-9887d9a1641e for the Endpoint URL.
6. For Authentication, select No authentication. If your specific endpoint requires authentication, select an existing connection or create a new one. For more information, see Creating API connections for bot builder.
7. Click Make API call.
8. Click Save next to results.

   

9. From the Value pulldown, select Order and then Image. Use the default variable name (image).
10. Click Add item and repeat the step above to create items for Order Status and Item. You can add up to 12 items (key value pairs.)

    

11. Click Save.

To create the dynamic carousel

1. In bot builder, click Add step under API call successful and select Add carousel.
2. In the Configuration panel, click Convert to dynamic message.
3. In the Array dropdown, click results. This is the array that you created above.
4. For title, click the plus sign and select results.item. You can enter up to 128 characters for the title and description.
5. For Button link, click the plus sign and select results.image.
6. For Button text, click the plus sign and select results.status.
7. For Image link, click the plus sign and select results.image.
8. Click Done.

   

To test your dynamic carousel

1. Add the orders answer to your bot.
2. Click Test bot.

   

About the step branches

The Make API call step is a branching step. Adding this step splits the bot responses depending on whether API was successfully executed.

If the API returned response code of either 400, 500, or 200 with data that is missing any of the variables, the bot will move down the failure branch

Attention: If you use the Make API call step, you acknowledge that the external system that you connect with is a Non-Zendesk Service (as defined in the Main Services Agreement). Zendesk does not operate or control the Non-Zendesk Services enabled through the use of the bot builder extensions feature and Zendesk is not responsible for the legal or regulatory compliance obligations of you or the Non-Zendesk Services.