Using variables to personalize AI agent answers (Legacy)

<body>
<p id="docs-hc-snippet" style="display: none;">In the bot builder, a variable is a container for data related to a conversation, such as a customer's name or a store order ID. During a conversation, an AI agent for messaging can utilize variables in many ways, including:</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">
<div class="note attention" id="topic_bsf_x3h_twb__note_zkd_dk2_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>
</div>
<p class="p">In the bot builder, a variable is a container for data related to a conversation, such as
a customer's name or a store order ID. During a conversation, an AI agent for messaging
can utilize variables in many ways, including:</p>
<div class="p">
<ul class="ul" id="topic_bsf_x3h_twb__ul_u5d_xp5_dbc">
<li class="li">Inserted into AI agent messages to personalize text responses, display dynamic
information and images, or branch the conversation. </li>
<li class="li">To set a value for a variable based on an end user's input.
</li>
<li class="li">In tags that are added to tickets during the Transfer to agent
step.
</li>
</ul>
</div>
<p class="p">An AI agent can include up to 46 <em class="ph i">unique</em> variables across all answers. Each unique
variable can be used in an answer as many times as needed.</p>
<div class="p">This article includes the following topics:<ul class="ul" id="topic_bsf_x3h_twb__ul_itg_zph_twb">
<li class="li"><a class="xref" href="#topic_up4_3jh_twb">About variable names and values</a></li>
<li class="li"><a class="xref" href="#topic_t2y_bkh_twb">About variable types</a></li>
<li class="li"><a class="xref" href="#id_kz3_dqh_twb">Using variables in an answer</a></li>
<li class="li"><a class="xref" href="#topic_yx5_vq5_dbc">Using variables in tags</a></li>
</ul>
</div>
</div>
<div aria-labelledby="ariaid-title2" class="topic nested1" id="topic_up4_3jh_twb">
<h2 class="title topictitle2" id="ariaid-title2">About variable names and values</h2>
<div class="body">
<p class="p">In the bot builder, each variable has a <em class="ph i">name</em> and <em class="ph i">value</em>. When
configuring a step in an answer, the name acts as a placeholder for the value. When
the AI agent runs the answer, it replaces the variable's name with the variable's
value. For example, you can use a variable named <strong class="ph b">Email</strong> as a placeholder for
the customer's email address.</p>
<div class="p">
<div class="note">
<span class="notetitle">Note:</span> Only the first 280 characters of a variable's value appear in the response
displayed in the messaging conversation.</div>
</div>
<p class="p">Variables are global within an AI agent. After they're created, variables are
available in all subsequent answers in the end user's conversation via free text or
the Link to another answer step.</p>
</div>
<div aria-labelledby="ariaid-title3" class="topic nested2" id="topic_wf3_vjh_twb">
<h3 class="title topictitle3" id="ariaid-title3">Handling empty variables</h3>
<div class="body">
<p class="p">A variable is empty if it has no value. AI agents skip empty variables during a
conversation.</p>
<p class="p">For example, a <strong class="ph b">Send message</strong> step includes an AI agent message of "Your
package's shipping status is <strong class="ph b">shipping_status</strong>." If the
<strong class="ph b">shipping_status</strong> variable is empty during a conversation, the AI agent
sends "Your package's shipping status is ."</p>
<div class="p">
<table border="1" cellpadding="4" cellspacing="0" class="simpletable" id="topic_wf3_vjh_twb__simpletable_c5d_clz_5wb" summary="">
<col style="width:50%">
<col style="width:50%">
<thead>
<tr class="sthead">
<th class="stentry" id="d88e141" style="vertical-align:bottom;text-align:left;">AI agent message</th>
<th class="stentry" id="d88e144" style="vertical-align:bottom;text-align:left;">Customer view</th>
</tr>
</thead>
<tbody>
<tr class="strow">
<td class="stentry" headers="d88e141" style="vertical-align:top;">
<img class="image img-screenshot" id="topic_wf3_vjh_twb__image_jnl_clz_5wb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/fb-empty-var-example-bot-message.png" width="400">
</td>
<td class="stentry" headers="d88e144" style="vertical-align:top;">
<img class="image img-screenshot" id="topic_wf3_vjh_twb__image_ort_clz_5wb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/fb-empty-var-example-conversation.png" width="300">
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title4" class="topic nested2" id="topic_pd3_5hy_fyb">
<h3 class="title topictitle3" id="ariaid-title4">Handling missing variables </h3>
<div class="body">
<p class="p">In the <strong class="ph b">Make API call</strong> step, if one of the saved variables is missing from
the response, the step's Fail branch is triggered. See <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4572971586586" target="_blank">Using the Make API call step in bot builder
(Legacy)</a>.</p>
</div>
</div>
<div aria-labelledby="ariaid-title5" class="topic nested2" id="topic_xrh_vsf_3fc">
<h3 class="title topictitle3" id="ariaid-title5">Handling variables with no source</h3>
<div class="body">
<p class="p">Normally, variables in the bot builder appear with a gray background. However, if
a variable's source has been removed, it appears with a red background instead.
For example, consider the following scenario:</p>
<ol class="ol" id="topic_xrh_vsf_3fc__ol_syg_dvf_3fc">
<li class="li">Within an answer flow, you add a Set variable step and use it to create and
set a variable called <strong class="ph b">shipping_status</strong>.</li>
<li class="li">As the next step of the flow, you add a Send message step and include the
<strong class="ph b">shipping_status</strong> variable as part of the message.<p class="p"><img class="image" id="topic_xrh_vsf_3fc__image_cyq_cwf_3fc" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/aia_variable_gray.png" width="250"></p>
</li>
<li class="li">You delete the Set variable step you created above.<p class="p">Because the source of
the shipping_status variable no longer exists, it now appears in red in
the Send message step.</p>
<p class="p"><img class="image" id="topic_xrh_vsf_3fc__image_oy1_dwf_3fc" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/aia_variable_red.png" width="250"></p>
</li>
</ol>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title6" class="topic nested1" id="topic_t2y_bkh_twb">
<h2 class="title topictitle2" id="ariaid-title6">About variable types</h2>
<div class="body">
<div class="p">Bot builder organizes variables based on how they're created and the data they
store:<ul class="ul" id="topic_t2y_bkh_twb__ul_uhr_dkh_twb">
<li class="li"><a class="xref" href="#topic_yyz_dkh_twb">Customer variables</a></li>
<li class="li"><a class="xref" href="#topic_rq2_tkh_twb">External service variables</a></li>
<li class="li"><a class="xref" href="#topic_eww_3lh_twb">Messaging metadata variables</a></li>
<li class="li"><a class="xref" href="#topic_lcx_2ft_dyb">Sunshine conversations
variables</a></li>
</ul>
</div>
</div>
<div aria-labelledby="ariaid-title7" class="topic nested2" id="topic_yyz_dkh_twb">
<h3 class="title topictitle3" id="ariaid-title7">Customer variables</h3>
<div class="body">
<p class="p">Customer variables store information provided by a customer during an <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408836323738#topic_i5r_grz_n5b" target="_blank">Ask for details</a> step. For example, the
step may ask a customer to provide their name and email address. </p>
<p class="p">When inserting a variable in a step using the <strong class="ph b">Add a variable</strong> icon (<img class="image" height="15" id="topic_yyz_dkh_twb__image_knm_1ml_nwb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/add-variable-icon.png" width="15">) , customer variables appear
under <strong class="ph b">Responses from customer</strong>.</p>
<p class="p"><img class="image img-screenshot" id="topic_yyz_dkh_twb__image_av4_2pr_nwb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/flow-builder-customer-variables-ex.png" width="250"></p>
</div>
</div>
<div aria-labelledby="ariaid-title8" class="topic nested2" id="topic_rq2_tkh_twb">
<h3 class="title topictitle3" id="ariaid-title8">External service variables</h3>
<div class="body">
<p class="p">External service variables store data received from an external system during a
<a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408836323738#topic_d4z_fwm_2tb" target="_blank">Make API call</a> step. For example, the
step can make a REST API request to a shipping provider to fetch the current
status of a package.</p>
<p class="p">Admins create external service variables when configuring the
<strong class="ph b">Make API
call</strong>
step. As part of the configuration, the admin can set a custom name
for each variable.</p>
<p class="p">When inserting a variable in a step using the
<strong class="ph b">Add a variable</strong>
icon (
<img class="image" height="15" id="topic_rq2_tkh_twb__image_wbr_glh_twb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/add-variable-icon.png" width="15">), external service
variables appear under
<strong class="ph b">Responses from external service</strong>.</p>
<p class="p"><img class="image img-screenshot" id="topic_rq2_tkh_twb__image_mfj_4zh_twb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/flow-builder-external-service-variables-ex.png" width="250"></p>
</div>
</div>
<div aria-labelledby="ariaid-title9" class="topic nested2" id="topic_eww_3lh_twb">
<h3 class="title topictitle3" id="ariaid-title9">Messaging metadata variables</h3>
<div class="body">
<p class="p">Messaging metadata variables contain information about a customer's identity and
authentication status. Messaging metadata variables get their values from the
signed JSON Web Tokens (JWTs) used for
<a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4411666638746" target="_blank">messaging authentication</a>.</p>
<p class="p">Messaging metadata variables aren't enabled by default and are only available for the Web Widget
and mobile SDK channels. For more information about enabling and using messaging
metadata variables, see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5314129059482" target="_blank">Using authentication metadata in an AI agent
answer</a>.</p>
<p class="p">If enabled, messaging metadata variables appear under <strong class="ph b">Messaging metadata</strong> when
inserting a variable in a step using the <strong class="ph b">Add a variable</strong> icon (<img class="image" height="15" id="topic_eww_3lh_twb__image_xpp_vlh_twb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/add-variable-icon.png" width="15">) ,</p>
<p class="p"><img class="image img-screenshot" id="topic_eww_3lh_twb__image_sxl_pzh_twb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/flow-builder-metadata-variables-ex.png" width="250"></p>
</div>
</div>
<div aria-labelledby="ariaid-title10" class="topic nested2" id="topic_lcx_2ft_dyb">
<h3 class="title topictitle3" id="ariaid-title10">Sunshine conversations variables</h3>
<div class="body">
<p class="p">Sunshine conversations variables can be used to connect to your <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5514406080538" target="_blank">Sunshine Conversations
integrations</a>.</p>
<p class="p">Available variables include:</p>
<div class="p">
<ul class="ul" id="topic_lcx_2ft_dyb__ul_oht_nft_dyb">
<li class="li">
<a class="xref" href="https://docs.smooch.io/rest/#tag/Users" target="_blank">SunCo user id </a>
</li>
<li class="li">
<a class="xref" href="https://docs.smooch.io/rest/#tag/Conversations" target="_blank">SunCo conversation id</a>
</li>
<li class="li">
<a class="xref" href="https://docs.smooch.io/rest/#tag/Apps" target="_blank">SunCo app id </a>
</li>
</ul>
</div>
<p class="p">
<img class="image" id="topic_lcx_2ft_dyb__image_qvy_qht_dyb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/bot_builder-sunco_variables.png" width="250">
</p>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title11" class="topic nested1" id="id_kz3_dqh_twb">
<h2 class="title topictitle2" id="ariaid-title11">Using variables in an answer </h2>
<div class="body">
<div class="p">With the bot builder, you can use inserted variables to:<ul class="ul" id="id_kz3_dqh_twb__ul_rh1_l4h_twb">
<li class="li"><a class="xref" href="#topic_jj3_l4h_twb">Customize AI agent messages</a></li>
<li class="li"><a class="xref" href="#topic_uzb_w4h_twb">Send data to external systems</a></li>
<li class="li"><a class="xref" href="#topic_tr4_2ph_twb">Branch an answer's flow</a></li>
<li class="li"><a class="xref" href="#topic_kkr_2q5_dbc">Set variable values</a></li>
</ul>
</div>
</div>
<div aria-labelledby="ariaid-title12" class="topic nested2" id="topic_jj3_l4h_twb">
<h3 class="title topictitle3" id="ariaid-title12">Customizing AI agent messages</h3>
<div class="body">
<div class="p">Admins can insert variables to the AI agent message of the following step
types:<ul class="ul" id="topic_jj3_l4h_twb__ul_xbp_m4h_twb">
<li class="li"><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408836323738#topic_mnf_gwc_k4b" target="_blank">Present options</a></li>
<li class="li"><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408836323738#topic_il3_pmj_tvb" target="_blank">Add carousel</a></li>
<li class="li"><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408836323738#topic_zqr_gwc_k4b" target="_blank">Transfer to agent</a></li>
<li class="li"><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408836323738#topic_iqz_fwc_k4b" target="_blank">Send message</a></li>
<li class="li"><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408836323738#topic_grj_gwc_k4b" target="_blank">Show help center articles</a></li>
</ul>
For example, the following AI agent message includes the <strong class="ph b">Name</strong>
variable.</div>
<img class="image img-screenshot" id="topic_jj3_l4h_twb__image_arl_wzh_twb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/flow-builder-bot-message-var-ex.png" width="300">
</div>
</div>
<div aria-labelledby="ariaid-title13" class="topic nested2" id="topic_uzb_w4h_twb">
<h3 class="title topictitle3" id="ariaid-title13">Sending data to external systems</h3>
<div class="body">
<p class="p">When making a REST API call to an external system using the <strong class="ph b">Make API call</strong>
step, admins can add insert variables into the path and query string of the
step's <strong class="ph b">Endpoint URL</strong> field. For more information, see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4572971586586" target="_blank">Using the Make API call step in the bot
builder</a>.</p>
<img class="image img-screenshot" id="topic_uzb_w4h_twb__image_lwf_gb3_twb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/flow-builder-bot-message-endpoint-url-ex.png" width="400">
</div>
</div>
<div aria-labelledby="ariaid-title14" class="topic nested2" id="topic_tr4_2ph_twb">
<h3 class="title topictitle3" id="ariaid-title14">Branching an answer's flow</h3>
<div class="body">
<div class="p">The <strong class="ph b">Branch by condition</strong> step lets an admin branch the flow of an answer
based on the value of one or more variables. For more information, see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5280598023450" target="_blank">Understanding branching
conditions</a>.<div class="note">
<span class="notetitle">Note:</span> Custom drop-down ticket fields use the <em class="ph i">Tag</em>
value as the variable’s value. </div>
</div>
<p class="p"><img class="image img-screenshot" id="topic_tr4_2ph_twb__image_dmm_hb3_twb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/flow-builder-bot-message-branch-by-condition-ex.png" width="300"></p>
</div>
</div>
<div aria-labelledby="ariaid-title15" class="topic nested2" id="topic_kkr_2q5_dbc">
<h3 class="title topictitle3" id="ariaid-title15">Setting variable values</h3>
<div class="body">
<p class="p">Admins can use the <strong class="ph b">Set variable </strong> step to create a new variable and assign
a value or to select an existing variable and overwrite its value based on an
end user's actions in a conversation. Variables can be referenced across all
answers in the AI agent. </p>
<p class="p">See <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408836323738#topic_utv_jq5_dbc" target="_blank">Understanding answer step types: Set
variable</a> for usage details.</p>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title16" class="topic nested1" id="topic_yx5_vq5_dbc">
<h2 class="title topictitle2" id="ariaid-title16"><strong class="ph b">Using variables in tags</strong></h2>
<div class="body">
<p class="p">Admins can use variables in the tags that are added to a ticket created as
part of the <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408836323738-Understanding-answer-step-types#topic_zqr_gwc_k4b" target="_blank">Transfer to agent step</a>. These tags can be
used by agents to view, organize, and track tickets, and in automated actions such
as ticket routing and other business rules. </p>
<p class="p">Although they are technically part of an answer, variables in tags are
subject to some rules and restrictions that other variables aren’t.</p>
<p class="p">You can use variables generated from API calls and system variables. Available
variables appear in the selection drop-down:</p>
<p class="p"><img class="image" id="topic_yx5_vq5_dbc__image_njz_gr5_dbc" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/add_variable_tag.png" width="300"></p>
<p class="p">However, variables containing input from end users can’t be used in tags. They
will appear in the drop-down list but will be disabled. For example, you can’t refer
to a variable using information collected in an <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408836323738#topic_i5r_grz_n5b" target="_blank">Ask for details step</a> earlier in the
conversation.</p>
<p class="p">The following rules and recommendations apply to using variables in
tags:</p>
<p class="p"><strong class="ph b">Character limit</strong></p>
<ul class="ul" id="topic_yx5_vq5_dbc__ul_nnq_kr5_dbc">
<li class="li">Hard-coded tags are limited to 80 characters each.
</li>
</ul>
<p class="p"><strong class="ph b">Special characters</strong></p>
<ul class="ul" id="topic_yx5_vq5_dbc__ul_onq_kr5_dbc">
<li class="li">Variables containing the following special characters can't be used and won't appear as available variables: <strong class="ph b">£</strong>, <strong class="ph b">`</strong>, <strong class="ph b">´</strong>, <strong class="ph b">\</strong>,
<strong class="ph b">[</strong>, <strong class="ph b">]</strong>, <strong class="ph b">{</strong>, <strong class="ph b">}</strong>, <strong class="ph b">(</strong>, <strong class="ph b">)</strong>, <strong class="ph b">&lt;</strong>, <strong class="ph b">&gt;</strong>, <strong class="ph b">%</strong>, <strong class="ph b">&amp;</strong>, <strong class="ph b">?</strong>, <strong class="ph b">+</strong>, <strong class="ph b">@</strong>, <strong class="ph b">!</strong>,
<strong class="ph b">*</strong>, <strong class="ph b">$</strong>, <strong class="ph b">#</strong>, <strong class="ph b">=</strong>, and <strong class="ph b">"</strong>
</li>
<li class="li">Space or commas used in variables appear as underscores in tags.
</li>
</ul>
<p class="p"><strong class="ph b">Additionally, we recommend the following best practices when using variables as tags: </strong></p>
<ul class="ul" id="topic_yx5_vq5_dbc__ul_sf5_lr5_dbc">
<li class="li">Tags are typically used for routing conversations or in trigger conditions. If
you want to add information to tickets for agent context, we recommend using
<a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4420210121114" target="_blank">custom fields</a>. </li>
<li class="li">Limit the number of possible values for a variable. Too many values can cause unexpected behaviors.
</li>
<li class="li">Keep value options short to avoid having them truncated as tags.
</li>
<li class="li">Avoid having special characters in the values.
</li>
</ul>
</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/5480101976218",
"url": "https://support.zendesk.com/hc/en-us/articles/5480101976218",
"headline": "Using variables to personalize AI agent answers (Legacy)",
"description": "You can use variables in the bot builder to personalize AI agent messages, set and use data throughout conversations, and apply variables in tags for ticket management, with specific rules for variable types and usage.",
"articleSection": "Using bot builder to create answers (Legacy)",
"datePublished": "2023-03-09T16:54:55+00:00",
"dateModified": "2026-05-12T16:30:56.952109+00:00",
"inLanguage": "en-US",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/5480101976218"
},
"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>