Using the Make an API call step in Flow Builder

The Make an 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 bot flow.

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

This article includes the following sections:

• Adding a Make an API call step to your bot
• Adding API details
• Saving the API response as a variable
• Authenticating the API call
• About the step branches

Adding a Make an API call step to your bot

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

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

To add a Make an API call step

1. Open the bot in Flow 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 an 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.
4. Optionally, select a connection to authenticate the API call.
   Note: You must create a connection before authenticating the API call.
5. If needed, enter the key and value for an optional header.
6. Click the Make Test API Call button to make a test 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. Please note this will make an HTTP request to the configured endpoint URL.

Saving the API response as a variable

A variable is a way to store API responses. Variables can be used in a few different ways:

• Personalizing the bot's message to customers. For example, you can save a customer's name as a variable and refer to it in a bot message. You can add variables anywhere in the flow after the Make an API call step in which the variable was created, in steps that include a configurable message:
  • Send message
  • Present options
  • Show help center articles
  • Transfer to agent

• Passing data in the call to an external system. For example, you can prompt a customer to provide an order number and then make an API call to your eCommerce system for shipment status for this particular order. When using variables on the Make an API call step, there are a few restrictions to be aware of.

  In the Endpoint URL field, variables can be added only to the URL path or query string values. Variables cannot be used in the domain or subdomain part of the URL. The table below shows examples of what you can or cannot do with variables:

  Valid configuration	Invalid configuration
  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 becomes invalid (if the API schema is changed, for example) the bot will skip the variable when displayed to the end user. You can create up to eight variables in a Make an API call step.

Note: The value of variables are not auto-translated. Keep this in mind if you use automatic translation in your messaging conversations.

After configuring the API details and testing the API call, you can use the returned Response data to create your variables. The steps below are a continuation of the procedure in the previous section.

To create a variable from the Response data

1. In the Configuration panel, click Make an 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.

Authenticating the API call

In the Make an API call step, you can use a connection to authenticate API calls to the external service or system.

To do this, you first must create the connection in Admin Center. A connection lets you safely store and pass credentials for the service. See Creating connections in Admin Center for more information and detailed instructions.

If you are having troble adding the connection, consult the Audit Log in admin Center for more information.

About the step branches

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

At bot run time, any 200 response codes will have the bot moving down the successful branch. All 400 or 500 response codes will have the bot moving down the failed branch. Please note that if the API returned 200 with an empty response, any variables saved from this step will be skipped at runtime.

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