Using the Make API call step in an AI agent for messaging (Legacy)

<body>
<p id="docs-hc-snippet" style="display: none;">In this article, we’ll walk you through the procedures involved in including and configuring the step in an AI agent for messaging.</p>
<div class="article-banners">
<div id="docs-wmp-link">
<a href="https://support.zendesk.com/hc/en-us/articles/5411234991258-plan" rel="noopener" target="_blank">What's my plan?</a>
</div>
<div class="article-banner" id="suite_all">
<table>
<tbody>
<tr>
<td>
<strong>All Suites</strong>
</td>
<td>Team, Growth, Professional, Enterprise, or Enterprise Plus</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="body">
<div class="p" id="topic_pkl_txg_4tb__note_owy_qnb_hbc">
<div class="note attention" id="topic_pkl_txg_4tb__note_ccj_jhk_f2c">
<span class="attentiontitle"></span> <span class="ph">This article describes functionality that moved into legacy
status on February 2, 2025. On December 10, 2026, this functionality will no longer
be available. For more information, see <a href="https://support.zendesk.com/hc/en-us/articles/10487730059034" target="_blank">this announcement</a>.</span>
</div>
The <strong class="ph b">Make API call</strong> 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.</div>
<p class="p">In this article, we’ll walk you through the procedures involved in including and configuring the
step in an AI agent for messaging.</p>
<p class="p">For an overview of the <strong class="ph b">Make API call</strong> step and its configuration rules, see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408836323738#topic_d4z_fwm_2tb" target="_blank">Understanding AI agent step types: Make API call</a>.</p>
<p class="p">This article includes the following sections:</p>
<div class="p">
<ul class="ul" id="topic_pkl_txg_4tb__ul_lnj_y1h_4tb">
<li class="li"><a class="xref" href="#topic_ypt_g1h_4tb">Adding a Make API call step to your AI agent</a></li>
<li class="li"><a class="xref" href="#topic_gnx_k1h_4tb">Adding API details</a></li>
<li class="li"><a class="xref" href="#topic_dph_l1h_4tb">Saving variables from the API response</a></li>
<li class="li"><a class="xref" href="#topic_tym_l1h_4tb">About the step branches</a></li>
</ul>
</div>
</div>
<div aria-labelledby="ariaid-title2" class="topic nested1" id="topic_ypt_g1h_4tb">
<h2 class="title topictitle2" id="ariaid-title2">Adding a Make API call step to your AI agent</h2>
<div class="body">
<div class="div">
<p class="p">Adding the <strong class="ph b">Make API call</strong> step to your AI agent includes a number of distinct tasks.</p>
<div class="p">The procedures below assume you have already <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408838909210#topic_o2h_qcy_fnb" target="_blank">created an AI agent for messaging</a>, and are adding
this step to that AI agent. <div class="note">
<span class="notetitle">Note:</span> If the system being called doesn't respond
within 10 seconds, the call will time out. </div>
</div>
<p class="p"><strong class="ph b">To add a Make API call step</strong></p>
<ol class="ol" id="topic_ypt_g1h_4tb__ol_rmf_5hh_4tb">
<li class="li"><span class="ph">In <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4581766374554#topic_hfg_dyz_1hb" target="_blank">Admin Center</a>, click <img class="image" id="topic_ypt_g1h_4tb__d9e1351" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/icon_ai.png">
<strong class="ph b">AI</strong> in the sidebar, then select <strong class="ph b">AI agents &gt; AI agents</strong>.</span></li>
<li class="li">Click the name of the AI agent you want to edit.</li>
<li class="li">Click the <strong class="ph b">Answers tab</strong>, then create a new answer or open an existing
answer.</li>
<li class="li">In bot builder, click the <strong class="ph b">Add step</strong> icon where you want to insert the step, either at the
end of a branch, or between two existing steps.</li>
<li class="li">In the Configuration panel, click
<strong class="ph b">Make API call</strong>.</li>
<li class="li">Enter descriptive information for the step. <ul class="ul" id="topic_ypt_g1h_4tb__ul_shy_whh_4tb">
<li class="li">
<strong class="ph b">Name</strong>: A name for the call that makes it easy for your team to
identify.</li>
<li class="li">
<strong class="ph b">Description</strong> (optional): A short description of the action
taken by the call.</li>
</ul>
<p class="p">This information will not be visible to customers.</p>
</li>
<li class="li">Continue with the procedure described in <a class="xref" href="#topic_gnx_k1h_4tb">Adding API details</a>.</li>
</ol>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title3" class="topic nested1" id="topic_gnx_k1h_4tb">
<h2 class="title topictitle2" id="ariaid-title3">Adding API details</h2>
<div class="body">
<p class="p">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.</p>
<p class="p">The API calls you configure here originate from <a class="xref" href="https://developer.zendesk.com/api-reference/ticketing/account-configuration/public_ips/" target="_blank">Zendesk public IP addresses</a>. To help
ensure these calls work as expected, make sure you configure your firewall settings
as needed. For more information, see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408842860186" target="_blank">Configuring your firewall for use with Zendesk</a>.</p>
<p class="p"><strong class="ph b">To add the API details</strong></p>
<ol class="ol" id="topic_gnx_k1h_4tb__ol_m4p_13h_4tb">
<li class="li">In the Configuration panel, click
<strong class="ph b">API details</strong>.</li>
<li class="li">Select a <strong class="ph b">Request method</strong>: <div class="p">
<ul class="ul" id="topic_gnx_k1h_4tb__ul_flx_f3h_4tb">
<li class="li">
<strong class="ph b">GET</strong> retrieves an external resource from the API service.
This is the most commonly used method.</li>
<li class="li">
<strong class="ph b">POST</strong> sends data to create a resource in an external
system. If the resource already exists, the data sent modifies the
resource.</li>
<li class="li">
<strong class="ph b">PUT</strong> sends data to update a resource.</li>
<li class="li">
<strong class="ph b">PATCH</strong> sends data to update a resource at an external site. It
is used to apply partial modifications to the resource.</li>
<li class="li">
<strong class="ph b">DELETE</strong> removes the resource at the external location.</li>
</ul>
</div>
</li>
<li class="li">Enter an <strong class="ph b">Endpoint URL</strong>.<p class="p">The endpoint URL is the location of the external resource you
are connecting to. The endpoint URL supports the
<code class="ph codeph">https://</code>protocol. You can include <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5480101976218" target="_blank">variables</a> in the URL's path or query string
values. For more information, see <a class="xref" href="#topic_m22_md3_twb">Passing variables in an API call</a>.</p>
</li>
<li class="li">Optionally, select a connection to authenticate the API call.
<div class="note">
<span class="notetitle">Note:</span> You must
<a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5040378297626-Creating-connections-in-Admin-Center" target="_blank">create a connection</a>
before using
it in the
<strong class="ph b">Make API call</strong>
step.
</div>
</li>
<li class="li">If needed, enter the key and value for an optional header. <div class="note important">
<span class="importanttitle">Important:</span> Don't use
headers for authentication. Use <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5040378297626-Creating-connections-in-Admin-Center" target="_blank">API connections</a> instead. <p class="p"><strong class="ph b">Make API call</strong>
steps that include authentication-related headers, such as
<code class="ph codeph">authorization</code> or <code class="ph codeph">x-api-key</code>,
automatically fail. If a <strong class="ph b">Make API call</strong> step fails, the
conversation follows the step's <strong class="ph b">API call failed</strong>
branch.</p>
</div>
</li>
<li class="li">Click <strong class="ph b">Make API Call</strong> to test the API call. <p class="p">If <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5480101976218" target="_blank">variables</a> 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.</p>
</li>
</ol>
</div>
<div aria-labelledby="ariaid-title4" class="topic nested2" id="topic_m22_md3_twb">
<h3 class="title topictitle3" id="ariaid-title4">Passing variables in an API call</h3>
<div class="body">
<p class="p">When you enter an
<strong class="ph b">Endpoint URL</strong> for an API call, you can include
<a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5480101976218" target="_blank">variables</a>
in the URL's path or query
string values. This lets you pass data from the conversation to the external
system.</p>
<p class="p">For example, a messaging AI agent can prompt a customer to provide an order number using an
<strong class="ph b">Ask for details</strong> step. The AI agent can then use a <strong class="ph b">Make API
call</strong> step get the shipping status for the order from your online
store.</p>
<p class="p">You can't use variables in the domain or subdomain of an endpoint URL. The
following table includes examples of valid and invalid
<strong class="ph b">Endpoint URL</strong> values.</p>
<div class="p">
<table border="1" cellpadding="4" cellspacing="0" class="simpletable" id="topic_m22_md3_twb__simpletable_n4q_vd3_twb" summary="">
<col style="width:50%">
<col style="width:50%">
<thead>
<tr class="sthead">
<th class="stentry" id="d89e344" style="vertical-align:bottom;text-align:left;">
Valid Endpoint URL
</th>
<th class="stentry" id="d89e346" style="vertical-align:bottom;text-align:left;">
Invalid Endpoint URL
</th>
</tr>
</thead>
<tbody>
<tr class="strow">
<td class="stentry" headers="d89e344" style="vertical-align:top;">
<code class="ph codeph">https://myshopify.com/admin/api/orders/order_number.json</code><p class="p">Retrieve
an order by specifying the order ID from Shopify.</p>
<img class="image img-screenshot" id="topic_m22_md3_twb__image_o4q_vd3_twb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/endpoing_url_ex.png" width="300">
</td>
<td class="stentry" headers="d89e346" style="vertical-align:top;">
<p class="p"><code class="ph codeph">https://domain.com/api/search?input=value</code></p>
<p class="p"><em class="ph i">Variables can’t be added to domain/subdomain</em></p>
</td>
</tr>
<tr class="strow">
<td class="stentry" headers="d89e344" style="vertical-align:top;">
<p class="p"><code class="ph codeph">https://maps.googleapis.com/maps/api/place?input=city_name</code></p>
<p class="p">Retrieve a location by keyword searches from Google’s places
API.</p>
</td>
<td class="stentry" headers="d89e346" style="vertical-align:top;">
<p class="p"><code class="ph codeph">https://example.com/api/search?key=value</code></p>
<p class="p"><em class="ph i">Variables can’t be added to query string key</em></p>
</td>
</tr>
</tbody>
</table>
</div>
<p class="p">If a variable is invalid or empty, the AI agent skips the variable during a conversation.</p>
<div class="p">
<div class="note">
<span class="notetitle">Note:</span>
Variable values are
<em class="ph i">not</em>
auto-translated. Keep this in mind if you
use automatic translation in your messaging conversations.
</div>
</div>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title5" class="topic nested1" id="topic_dph_l1h_4tb">
<h2 class="title topictitle2" id="ariaid-title5">Saving variables from the API response</h2>
<div class="body">
<p class="p">After configuring details and testing the API call, you can save values from the API call's JSON
response as <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5480101976218" target="_blank">variables</a>. You can save up to 12 variables in a <strong class="ph b">Make
API call</strong> step. Only the first 280 characters of a variable's value are
saved. </p>
<p class="p"><strong class="ph b">To create a variable from the Response data</strong></p>
<ol class="ol" id="topic_dph_l1h_4tb__ol_s2z_jjh_4tb">
<li class="li">In the Configuration panel, click
<strong class="ph b">Make API call</strong>.</li>
<li class="li">Expand the accordion and identify the data from external system that you want to
turn into a variable.
<div class="p">
<div class="note tip" id="topic_dph_l1h_4tb__note_kwv_1qx_hzb">
<span class="tiptitle">Tip:</span> Switch to the Response body tab to
view the raw response that has came back from the external
system.
</div>
</div>
</li>
<li class="li">Click
<strong class="ph b">Save</strong>.</li>
<li class="li">Give the new variable a name.<p class="p">Variable names must include only lowercase letters, numbers, and
underscores.</p>
</li>
</ol>
</div>
</div>
<div aria-labelledby="ariaid-title6" class="topic nested1" id="topic_lwv_1qx_hzb">
<h2 class="title topictitle2" id="ariaid-title6">Passing array variables in an API call</h2>
<div class="body">
<div class="p">You can pass array variables using
<strong class="ph b">Make API call</strong>
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.
<pre class="pre codeblock" id="topic_lwv_1qx_hzb__codeblock_i1w_1qx_hzb"><code>{
"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",
…
</code></pre>
</div>
<div class="p">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,
<code class="ph codeph">id</code>,
<code class="ph codeph">name</code>,
<code class="ph codeph">address</code>,
<code class="ph codeph">item</code>,
<code class="ph codeph">price</code>, and
<code class="ph codeph">image</code>are
all displayed. This data is typically passed to a carousel, however the carousel can
display only up to 10 items.
<div class="note" id="topic_lwv_1qx_hzb__note_j1w_1qx_hzb">
<span class="notetitle">Note:</span> Only the first 280
characters of a property value appear in the response.
</div>
</div>
<div class="p">Nested JSON arrays can also be saved as array variables. For example, given
the following JSON output,
<code class="ph codeph">lastname</code>and
<code class="ph codeph">firstname</code>can be saved as separate array
variables.
<pre class="pre codeblock" id="topic_lwv_1qx_hzb__codeblock_k1w_1qx_hzb"><code>"name":
{
"lastname": "Cummings”,
"firstname": “Alexander"
},
</code></pre>
</div>
<p class="p">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.</p>
<div class="p">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
<code class="ph codeph">{{customer.order}}</code> 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.
<pre class="pre codeblock" id="topic_lwv_1qx_hzb__codeblock_l1w_1qx_hzb"><code>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}}
</code></pre>
</div>
<p class="p">
<strong class="ph b">Example</strong>
</p>
<div class="p"> In this example, an array variable is created using an API endpoint that returns an array of
orders. The orders array is specified by the "results" property in the following API
response snippet.
<pre class="pre codeblock" id="topic_lwv_1qx_hzb__codeblock_m1w_1qx_hzb"><code>
{
"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"
},
… </code></pre>
</div>
<p class="p"> This example uses <strong class="ph b">Make API call</strong> to create the array variable and then uses a
dynamic carousel to display the results to an end user. </p>
<p class="p">
<strong class="ph b">To create the array</strong>
</p>
<div class="p">
<ol class="ol" id="topic_lwv_1qx_hzb__ol_n1w_1qx_hzb">
<li class="li">In the Configuration panel, click
<strong class="ph b">Make API call</strong>.</li>
<li class="li">Enter
<strong class="ph b">orders</strong>
for the name.</li>
<li class="li">In the Configuration panel, click
<strong class="ph b">API details</strong>.</li>
<li class="li">Click the <strong class="ph b">Request method</strong> dropdown and select <strong class="ph b">GET</strong>.</li>
<li class="li">Enter the URL for the <strong class="ph b">Endpoint URL</strong>.</li>
<li class="li">For <strong class="ph b">Authentication</strong>, select your authentication method. <p class="p">For more information, see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5040378297626" target="_blank">Creating connections to integrate with external
services</a>.</p>
</li>
<li class="li">Click
<strong class="ph b">Make API call</strong>.</li>
<li class="li">Click
<strong class="ph b">Save</strong>
next to results.
<p class="p"><img class="image img-screenshot" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/makeapisaveresults.png" width="250"></p>
</li>
<li class="li">From the <strong class="ph b">Value</strong> dropdown, select <strong class="ph b">Order</strong> and then <strong class="ph b">Image</strong>.<p class="p">Use the default
variable name (image).</p>
</li>
<li class="li">Click <strong class="ph b">Add item</strong> and repeat the step above to create items for <strong class="ph b">Order Status</strong> and
<strong class="ph b">Item</strong>. <p class="p">You can add up to 12 items (or key-value
pairs).</p>
<p class="p"><img class="image img-screenshot" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/namearrayvariable.png"></p>
</li>
<li class="li">Click
<strong class="ph b">Save</strong>.</li>
</ol>
</div>
<div class="p">
<strong class="ph b">To create the dynamic carousel</strong>
<ol class="ol" id="topic_lwv_1qx_hzb__ol_o1w_1qx_hzb">
<li class="li">In bot builder, click <strong class="ph b">Add step</strong> under <strong class="ph b">API call successful</strong> and
select <strong class="ph b">Add carousel</strong>.</li>
<li class="li">In the Configuration panel, click <strong class="ph b">Convert to dynamic message</strong>.</li>
<li class="li">In the <strong class="ph b">Array</strong> dropdown, click <strong class="ph b">results</strong>. This is the array that
you created above.</li>
<li class="li">For title, click the plus sign and select <strong class="ph b">results.item</strong>. <p class="p">You can
enter up to 128 characters for the title and description.</p>
</li>
<li class="li">For <strong class="ph b">Button link</strong>, click the plus sign and select
<strong class="ph b">results.image</strong>.</li>
<li class="li">For <strong class="ph b">Button text</strong>, click the plus sign and select
<strong class="ph b">results.status</strong>.</li>
<li class="li">For <strong class="ph b">Image link</strong>, click the plus sign and select
<strong class="ph b">results.image</strong>.</li>
<li class="li">Click <strong class="ph b">Done</strong>. <p class="p"><img class="image img-screenshot" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/makeapiarray.png"></p>
</li>
</ol>
</div>
<p class="p"> Here's an example dynamic carousel.</p>
<p class="p">
<img class="image img-screenshot" id="topic_lwv_1qx_hzb__image_vls_thq_4bc" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/dynamiccarouseltest.gif">
</p>
</div>
</div>
<div aria-labelledby="ariaid-title7" class="topic nested1" id="topic_tym_l1h_4tb">
<h2 class="title topictitle2" id="ariaid-title7">About the step branches</h2>
<div class="body">
<p class="p">The <strong class="ph b">Make API call</strong> step is a branching step. Adding this step splits the AI agent responses
depending on whether the API request was successfully executed.</p>
<div class="p">The AI agent will move down the failure branch in the following cases:<ul class="ul" id="topic_tym_l1h_4tb__ul_gcq_dcz_ycc">
<li class="li">The API returns a 400 or 500 response code.</li>
<li class="li">One of the saved variables is missing or has a <code class="ph codeph">null</code>
value.</li>
</ul>
</div>
<p class="p">The AI agent will move down the success branch in all other cases. </p>
<div class="p">
<div class="note attention">
<span class="attentiontitle"></span> If you use the <strong class="ph b">Make API call</strong> step, you acknowledge that the external
system that you connect with is a Non-Zendesk Service (as defined in the <a class="xref" href="https://www.zendesk.com/company/agreements-and-terms/zendesk-customer-agreement/" target="_blank">Zendesk Customer Agreement</a>). 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. </div>
</div>
</div>
</div>
<script id="docs-schema-markup" type="application/ld+json">{
"@context": "https://schema.org",
"@type": "TechArticle",
"@id": "https://support.zendesk.com/hc/en-us/articles/4572971586586",
"url": "https://support.zendesk.com/hc/en-us/articles/4572971586586",
"headline": "Using the Make API call step in an AI agent for messaging (Legacy)",
"description": "You can configure an AI agent to make API calls to external systems, handle responses, and use the data within messaging conversations, with detailed steps for setup and variable management provided.",
"articleSection": "Using bot builder to create answers (Legacy)",
"datePublished": "2022-05-02T18:29:36+00:00",
"dateModified": "2026-05-12T16:34:16.628983+00:00",
"inLanguage": "en-US",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/4572971586586"
},
"author": {
"@type": "Organization",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
},
"publisher": {
"@type": "Organization",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
},
"isPartOf": {
"@type": "WebSite",
"name": "Zendesk Help",
"@id": "https://support.zendesk.com/hc/"
},
"about": {
"@type": "SoftwareApplication",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
}
}</script>
</body>