Messaging recipe: Getting external data for your AI agent for messaging (Legacy)

<body>
<p id="docs-hc-snippet" style="display: none;">In this recipe, you’ll create an AI agent answer that retrieves weather data for a location provided by an end user. The answer gets the data from theOpenWeather API. You can use the answer flow created in this recipe as a starting point for building your own API-powered answers.</p>
<div class="body">
<div class="p" id="msg_get_external_data_recipe__note_owy_qnb_hbc">
<div class="note attention" id="msg_get_external_data_recipe__note_f3s_4h2_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 <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4572971586586" target="_blank">Make API call</a> step lets an AI agent for messaging
use a REST API request to fetch data from an external system, such as Shopify or
Salesforce.</div>
<p class="p">In this recipe, you’ll create an AI agent answer that retrieves weather data for a location
provided by an end user. The answer gets the data from the <a class="xref" href="https://openweathermap.org/api" target="_blank">OpenWeather
API</a>. You can use the answer flow created in this recipe as a starting
point for building your own API-powered answers.</p>
<p class="p"><img class="image img-screenshot" id="msg_get_external_data_recipe__image_av4_2pr_nwb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/make-api-call-step-testing-bot.gif" width="300"></p>
<div class="p">The recipe involves the following tasks:
<ul class="ul" id="msg_get_external_data_recipe__ul_cgl_3gl_nwb">
<li class="li"><a class="xref" href="#topic_ufl_lgl_nwb">Task 1: Checking your setup</a></li>
<li class="li"><a class="xref" href="#topic_gbv_wgl_nwb">Task 2: Creating an API connection</a></li>
<li class="li"><a class="xref" href="#topic_eqy_fhl_nwb">Task 3: Creating a custom ticket field</a></li>
<li class="li"><a class="xref" href="#topic_ffc_shl_nwb">Task 4: Building an AI agent answer</a></li>
<li class="li"><a class="xref" href="#topic_evp_lml_nwb">Task 5: Testing your changes</a></li>
</ul>
<div class="note">
<span class="notetitle">Note:</span>
Zendesk provides this article for instructional purposes only. Zendesk
doesn't support the examples in this article. Zendesk also doesn’t support
third-party technologies, such as the OpenWeather API.
</div>
</div>
</div>
<div aria-labelledby="ariaid-title2" class="topic nested1" id="topic_ufl_lgl_nwb">
<h2 class="title topictitle2" id="ariaid-title2">Task 1: Checking your setup</h2>
<div class="body">
<p class="p">To complete this recipe, you’ll need the following:</p>
<ul class="ul" id="topic_ufl_lgl_nwb__ul_lhd_ngl_nwb">
<li class="li">A Zendesk account with a published AI agent for messaing. You can use a <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408828617370" target="_blank">sandbox testing environment</a> to test the
AI agent before using it in production. <p class="p">To set up an AI agent on a
web and mobile messaging channel, see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408824263578" target="_blank">Creating an AI agent for your web and
mobile channels</a>. For information about using
messaging in a sandbox environment, see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408844075930" target="_blank">Using messaging in your
sandbox</a>.</p>
</li>
<li class="li">An API key for an <a class="xref" href="https://openweathermap.org/" target="_blank">OpenWeather</a>account. The API used in this recipe is
available on OpenWeather’s free plan. <p class="p">To sign up for a free
OpenWeather account, see the Create New Account page on <a class="xref" href="https://home.openweathermap.org/users/sign_up" target="_blank">openweathermap.org</a>. After signing
in, you can get an API key on your <a class="xref" href="https://home.openweathermap.org/api_keys" target="_blank">OpenWeather account page</a>.</p>
To
activate OpenWeather API keys, you must verify your account email
address. After verification, API keys can take up to two hours to
activate. For more information, see the FAQ on <a class="xref" href="https://openweathermap.org/faq" target="_blank">openweathermap.org</a>.</li>
</ul>
</div>
</div>
<div aria-labelledby="ariaid-title3" class="topic nested1" id="topic_gbv_wgl_nwb">
<h2 class="title topictitle2" id="ariaid-title3">Task 2: Creating an API connection</h2>
<div class="body">
<p class="p">To start, create an API connection to store your OpenWeather API key. Your AI agent can use this
connection to authenticate calls to the OpenWeather API.</p>
<div class="p">
<strong class="ph b">To create the connection</strong>
<ol class="ol" id="topic_gbv_wgl_nwb__ol_lr5_bhl_nwb">
<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_gbv_wgl_nwb__d8e2105" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_apps_integrations_icon.png">
<strong class="ph b">Apps and integrations</strong> in the sidebar, then select <strong class="ph b">Connections &gt;
Connections</strong>.</span></li>
<li class="li">Click
<strong class="ph b">Create connection</strong>.</li>
<li class="li">Select the
<strong class="ph b">API key</strong>
authentication type.</li>
<li class="li">Enter
<strong class="ph b">openweather_api_key</strong> as the
<strong class="ph b">Connection name</strong>.</li>
<li class="li">Enter
<strong class="ph b">x-api-key</strong> as the
<strong class="ph b">Header name</strong>.</li>
<li class="li">Enter your OpenWeather API key as the
<strong class="ph b">Value</strong>.</li>
<li class="li">Enter
<strong class="ph b">api.openweathermap.org</strong> as the
<strong class="ph b">Allowed domain</strong>.</li>
<li class="li">Click
<strong class="ph b">Save</strong>
to create the connection.</li>
</ol>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title4" class="topic nested1" id="topic_eqy_fhl_nwb">
<h2 class="title topictitle2" id="ariaid-title4">Task 3: Creating a custom ticket field</h2>
<div class="body">
<p class="p">Next, create a custom ticket field to capture the location provided by the end
user.</p>
<div class="p">
<strong class="ph b">To create the custom ticket field</strong>
<ol class="ol" id="topic_eqy_fhl_nwb__ol_wjz_hhl_nwb">
<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_eqy_fhl_nwb__d8e1615" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_objects_rules_icon.png">
<strong class="ph b">Objects and rules</strong> in the sidebar, then select <strong class="ph b">Tickets &gt; Fields</strong>.</span></li>
<li class="li">Click
<strong class="ph b">Add field</strong>.</li>
<li class="li">Select the
<strong class="ph b">Text</strong>
field type.
<p class="p"><img class="image img-screenshot" id="topic_eqy_fhl_nwb__image_rlc_mlh_fvb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/hc_downvote_feedback_text_custom_field.png" width="500"></p>
</li>
<li class="li">Enter
<strong class="ph b">Location</strong>
as the
<strong class="ph b">Display name</strong>.</li>
<li class="li">Under
<strong class="ph b">Permissions</strong>, select
<strong class="ph b">Customers can edit</strong>.</li>
<li class="li">Under
<strong class="ph b">Customers</strong>, enter
<strong class="ph b">Location</strong>
as the
<strong class="ph b">Title shown to
customers</strong>.</li>
<li class="li">Click
<strong class="ph b">Save</strong>.</li>
</ol>
</div>
<p class="p">If your account uses a single ticket form, the new field automatically appears in
your ticket form. To remove the field, see
<a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408846520858#topic_c5x_l3b_lk" target="_blank">Editing ticket forms</a>.</p>
</div>
</div>
<div aria-labelledby="ariaid-title5" class="topic nested1" id="topic_ffc_shl_nwb">
<h2 class="title topictitle2" id="ariaid-title5">Task 4: Building an AI agent answer</h2>
<div class="body">
<p class="p">This section walks you through creating the answer, setting its intent, and adding
steps for the answer in the bot builder. This involves the following steps:</p>
<ul class="ul" id="topic_ffc_shl_nwb__ul_a4m_thl_nwb">
<li class="li"><a class="xref" href="#topic_sry_thl_nwb">Step 1: Creating the answer</a></li>
<li class="li"><a class="xref" href="#topic_kv1_f3l_nwb">Step 2: Setting the answer’s intent</a></li>
<li class="li"><a class="xref" href="#topic_ifq_33l_nwb">Step 3: Adding an initial message step</a></li>
<li class="li"><a class="xref" href="#topic_mpx_n3l_nwb">Step 4: Asking the end user for a location</a></li>
<li class="li"><a class="xref" href="#topic_hd2_rjl_nwb">Step 5: Retrieving weather data for the location</a></li>
<li class="li"><a class="xref" href="#topic_rgg_qkl_nwb">Step 6: Sending a weather message to the end user</a></li>
<li class="li"><a class="xref" href="#topic_zxc_vll_nwb">Step 7: Adding a failure message</a></li>
<li class="li"><a class="xref" href="#topic_u1q_3ml_nwb">Step 8: Publishing your updated AI agent</a></li>
</ul>
</div>
<div aria-labelledby="ariaid-title6" class="topic nested2" id="topic_sry_thl_nwb">
<h3 class="title topictitle3" id="ariaid-title6">Step 1: Creating the answer</h3>
<div class="body">
<p class="p">Use bot builder to create an answer for your AI agent.</p>
<div class="p">
<strong class="ph b">To create the answer</strong>
<ol class="ol" id="topic_sry_thl_nwb__ol_xs5_vhl_nwb">
<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_sry_thl_nwb__d8e1351" 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 AI agent you want to work with.</li>
<li class="li">On the Answers tab, click
<strong class="ph b">Create answer</strong>.</li>
</ol>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title7" class="topic nested2" id="topic_kv1_f3l_nwb">
<h3 class="title topictitle3" id="ariaid-title7">Step 2: Setting the answer’s intent</h3>
<div class="body">
<p class="p">Set the answer’s intent and training phrases. These include phrases and words
used to trigger the answer in a conversation.</p>
<div class="p">
<strong class="ph b">To set the answer’s intent</strong>
<ol class="ol" id="topic_kv1_f3l_nwb__ol_qyd_h3l_nwb">
<li class="li">On the Answers tab of the AI agent’s edit page, click <strong class="ph b">Create answer</strong>.</li>
<li class="li">Click <strong class="ph b">Build your own answer</strong>, then click <strong class="ph b">Next</strong>.</li>
<li class="li">Enter
<strong class="ph b">Get weather</strong>
as the answer’s
<strong class="ph b">Intent</strong>.</li>
<li class="li">Under
<strong class="ph b">Training phrases</strong>, enter
<strong class="ph b">Get weather forecast</strong>
and
<strong class="ph b">Get current temperature.</strong>
</li>
<li class="li">Click
<strong class="ph b">Next</strong>.
<p class="p">The answer opens in the bot builder where you can
build out the response.</p>
</li>
</ol>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title8" class="topic nested2" id="topic_ifq_33l_nwb">
<h3 class="title topictitle3" id="ariaid-title8">Step 3: Adding an initial message step</h3>
<div class="body">
<p class="p">Add a
<strong class="ph b">Send message</strong>
step to ask the user for a location. This is the first
step in the answer’s flow.</p>
<div class="p">
<strong class="ph b">To add an initial message step</strong><ol class="ol" id="topic_ifq_33l_nwb__ol_s1n_k3l_nwb">
<li class="li">In the bot builder, click
<strong class="ph b">Add step</strong>.</li>
<li class="li">Under
<strong class="ph b">Choose step</strong>, select
<strong class="ph b">Send message</strong>.</li>
<li class="li">In <strong class="ph b">AI agent message</strong>, enter the following text: <pre class="pre codeblock"><code>
What location would you like to get the weather for?

Include the country code. For example: "Melbourne, AU" or "San Francisco, US"
</code></pre>
</li>
</ol>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title9" class="topic nested2" id="topic_mpx_n3l_nwb">
<h3 class="title topictitle3" id="ariaid-title9">Step 4: Asking the end user for a location</h3>
<div class="body">
<p class="p">After the initial message, add an
<strong class="ph b">Ask for details</strong>
step to present a basic
form to the end user. The form includes a text box for the
<strong class="ph b">Location</strong>
ticket field’s value.</p>
<div class="p">
<strong class="ph b">To add an Ask for details step</strong><ol class="ol" id="topic_mpx_n3l_nwb__ol_rrx_p3l_nwb">
<li class="li">In the bot builder, click the
<strong class="ph b">Add step</strong> icon (
<img class="image" height="15" id="topic_mpx_n3l_nwb__image_jr3_4jl_nwb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/add-step-icon.png" width="15">).</li>
<li class="li">Under
<strong class="ph b">Choose step</strong>, select
<strong class="ph b">Ask for details</strong>.</li>
<li class="li">Enter
<strong class="ph b">Get location</strong>
as the
<strong class="ph b">Name</strong>.</li>
<li class="li">In
<strong class="ph b">Fields</strong>, type and select the
<strong class="ph b">Location</strong>
ticket field.</li>
</ol>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title10" class="topic nested2" id="topic_hd2_rjl_nwb">
<h3 class="title topictitle3" id="ariaid-title10">Step 5: Retrieving weather data for the location</h3>
<div class="body">
<p class="p">Add a
<strong class="ph b">Make API call</strong>
step to get weather data for the location from the
OpenWeather API’s
<a class="xref" href="https://openweathermap.org/current" target="_blank">Current weather data</a>
endpoint.</p>
<div class="p">
<strong class="ph b">To add a Make API call step</strong><ol class="ol" id="topic_hd2_rjl_nwb__ol_e4y_sjl_nwb">
<li class="li">In the bot builder, click
<strong class="ph b">Add step</strong>.</li>
<li class="li">Under
<strong class="ph b">Choose step</strong>, select
<strong class="ph b">Make API Call</strong>.</li>
<li class="li">Enter
<strong class="ph b">Get weather</strong>
as the
<strong class="ph b">Name</strong>.</li>
<li class="li">Under
<strong class="ph b">API details,</strong>
enter
<code class="ph codeph">https://api.openweathermap.org/data/2.5/weather?units=metric&amp;q=</code>as the
<strong class="ph b">Endpoint URL.</strong>
</li>
<li class="li">Use the <strong class="ph b">Add a variable</strong> icon ( <img class="image" height="15" id="topic_hd2_rjl_nwb__image_n3n_bkl_nwb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/add-variable-icon.png" width="15">) to append the
<strong class="ph b">Location</strong> field variable to the <strong class="ph b">Endpoint
URL</strong> value. <p class="p">The finished <strong class="ph b">Endpoint URL</strong>
value should look like this:</p>
<p class="p"><img class="image img-screenshot" id="topic_hd2_rjl_nwb__image_yyf_lkl_nwb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/make-api-call-step-openweather-url.png" width="600"></p>
</li>
<li class="li">In
<strong class="ph b">Authentication</strong>, select the
<strong class="ph b">openweather_api</strong> connection.</li>
<li class="li">To test the API request, click
<strong class="ph b">Make API call</strong>.</li>
<li class="li">Under
<strong class="ph b">Test Data</strong>, enter
<strong class="ph b">Melbourne, AU</strong>
as the
<strong class="ph b">Location</strong>.</li>
<li class="li">Click
<strong class="ph b">Make API call</strong>.</li>
<li class="li">Save the following variables using their default names:
<ul class="ul" id="topic_hd2_rjl_nwb__ul_jty_4kl_nwb">
<li class="li">
<strong class="ph b">main</strong>
&gt;
<strong class="ph b">temp</strong>
</li>
<li class="li">
<strong class="ph b">weather</strong>
&gt;
<strong class="ph b">item 1</strong>
&gt;
<strong class="ph b">description</strong>
</li>
</ul>
</li>
</ol>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title11" class="topic nested2" id="topic_rgg_qkl_nwb">
<h3 class="title topictitle3" id="ariaid-title11">Step 6: Sending a weather message to the end user</h3>
<div class="body">
<p class="p">After retrieving the weather data, use a
<strong class="ph b">Send message</strong>
step to respond with
a message containing the weather data.</p>
<div class="p">
<strong class="ph b">To add an API success message</strong>
<ol class="ol" id="topic_rgg_qkl_nwb__ol_yx3_fll_nwb">
<li class="li">In the bot builder, click
<strong class="ph b">Add step</strong> under the
<strong class="ph b">Get weather</strong>
step’s
<strong class="ph b">API call successful</strong>
branch.</li>
<li class="li">Under
<strong class="ph b">Choose step</strong>, select
<strong class="ph b">Send message</strong>.</li>
<li class="li">In <strong class="ph b">AI agent message</strong>, enter the following text: <pre class="pre codeblock"><code>
It's {{temp}}° C with {{description}} in
</code></pre>
</li>
<li class="li">Use the <strong class="ph b">Add a variable</strong> icon ( <img class="image" height="15" id="topic_rgg_qkl_nwb__image_ikr_kll_nwb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/add-variable-icon.png" width="15">) to append the
<strong class="ph b">Location</strong> field variable to the <strong class="ph b">AI agent
message</strong> value. Then add a period (.). <p class="p">The
finished <strong class="ph b">AI agent message</strong> value should look
like this:</p>
<p class="p"><img class="image img-screenshot" id="topic_rgg_qkl_nwb__image_xtn_qll_nwb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/make-api-call-step-recipe-success-msg.png" width="400"></p>
</li>
</ol>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title12" class="topic nested2" id="topic_zxc_vll_nwb">
<h3 class="title topictitle3" id="ariaid-title12">Step 7: Adding a failure message</h3>
<div class="body">
<p class="p">The request made during the
<strong class="ph b">Make API call</strong>
step may fail. For example, the
request may include a location that doesn’t exist. Add a
<strong class="ph b">Send message</strong>
step to the
<strong class="ph b">API call failed</strong>
branch. This step returns a message if the
OpenWeather API call fails.</p>
<div class="p">
<strong class="ph b">To add an API failure message</strong>
<ol class="ol" id="topic_zxc_vll_nwb__ol_zph_xll_nwb">
<li class="li">In the bot builder, click
<strong class="ph b">Add step</strong> under the
<strong class="ph b">Get weather</strong>
step’s
<strong class="ph b">API call failed</strong>
branch.</li>
<li class="li">Under
<strong class="ph b">Choose</strong>
step, select
<strong class="ph b">Send message</strong>.</li>
<li class="li">In <strong class="ph b">AI agent</strong> message, enter the following text: <pre class="pre codeblock"><code>
I'm sorry. I wasn't able to get weather data for
</code></pre>
</li>
<li class="li">Use the <strong class="ph b">Add a variable</strong> icon ( <img class="image" height="15" id="topic_zxc_vll_nwb__image_knm_1ml_nwb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/add-variable-icon.png" width="15">) to append the
<strong class="ph b">Location</strong> field variable to the <strong class="ph b">AI agent
message</strong> value. Then add a period (.). <p class="p">The
finished <strong class="ph b">AI agent message</strong> value should look
like this:</p>
<p class="p"><img class="image img-screenshot" id="topic_zxc_vll_nwb__image_v4c_bml_nwb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/make-api-call-step-recipe-fail-msg.png" width="400"></p>
</li>
</ol>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title13" class="topic nested2" id="topic_u1q_3ml_nwb">
<h3 class="title topictitle3" id="ariaid-title13">Step 8: Publishing your updated AI agent</h3>
<div class="body">
<p class="p">To push the answer live, publish the updated AI agent.</p>
<div class="p">
<strong class="ph b">To publish the AI agent</strong><ol class="ol" id="topic_u1q_3ml_nwb__ol_rkw_jml_nwb">
<li class="li">Click <strong class="ph b">Done</strong> in the upper right corner of the bot
builder.</li>
<li class="li">On the AI agent page, click <strong class="ph b">Publish AI agent</strong>.</li>
<li class="li">Click <strong class="ph b">Publish</strong>.</li>
</ol>
</div>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title14" class="topic nested1" id="topic_evp_lml_nwb">
<h2 class="title topictitle2" id="ariaid-title14">Task 5: Testing your changes</h2>
<div class="body">
<p class="p">After you publish your changes, you can test the new answer by asking “How’s the weather?” in a
conversation with the updated AI agent. For more information about testing
AI agents for messaging, see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408835784602" target="_blank">Testing the end user's messaging
experience</a>.</p>
<p class="p"><img class="image img-screenshot" id="topic_evp_lml_nwb__image_qm4_5ml_nwb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/make-api-call-step-testing-bot.gif" width="300"></p>
</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/5414486254618",
"url": "https://support.zendesk.com/hc/en-us/articles/5414486254618",
"headline": "Messaging recipe: Getting external data for your AI agent for messaging (Legacy)",
"description": "You can create an AI agent answer that retrieves weather data from an external API by setting up an API connection, creating a custom ticket field, and building a response flow with API calls and messaging steps.",
"articleSection": "Using bot builder to create answers (Legacy)",
"datePublished": "2023-02-16T18:21:24+00:00",
"dateModified": "2026-05-12T16:35:54.323127+00:00",
"inLanguage": "en-US",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/5414486254618"
},
"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>