Using authentication metadata in an AI agent answer (Legacy)

<body>
<p id="docs-hc-snippet" style="display: none;">Messaging metadata variables get their values from the signed JSON Web Tokens (JWTs) used formessaging authentication. During a conversation, a messaging AI agent can use this data to customize its responses, display information specific to the customer, or branch the conversation's flow.</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_fx2_krh_twb__note_yqr_pj2_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>
<a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5480101976218" target="_blank">Bot builder variables</a> let you customize a messaging
AI agent's answers based on data related to a conversation. Messaging metadata
variables are a type of variable used in the bot builder that contain information
about the current customer's identity and authentication status.</div>
<p class="p">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>. During a conversation, a
messaging AI agent can use this data to customize its responses, display
information specific to the customer, or branch the conversation's flow.</p>
<div class="p">This article includes the following topics:
<ul class="ul" id="topic_fx2_krh_twb__ul_b2r_3sh_twb">
<li class="li"><a class="xref" href="#topic_ktn_xlh_twb">Enabling messaging metadata variables</a></li>
<li class="li"><a class="xref" href="#topic_lwy_kmh_twb">Supported messaging metadata variables</a></li>
<li class="li"><a class="xref" href="#topic_jzh_pnh_twb">Best practices for using messaging metadata variables</a></li>
</ul>
</div>
<p class="p">For a broader overview of the AI agent variables and how you can use them in answers, see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5480101976218" target="_blank">Using variables to personalize AI agent answers</a>.</p>
</div>
<div aria-labelledby="ariaid-title2" class="topic nested1" id="topic_ktn_xlh_twb">
<h2 class="title topictitle2" id="ariaid-title2">Enabling messaging metadata variables</h2>
<div class="body">
<p class="p">Messaging metadata variables aren't enabled by default. To enable messaging metadata variables, an admin
must
<a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4411666638746#topic_pyg_kqx_3sb" target="_blank">create a signing key</a>
used to generate JWTs
for messaging authentication. Messaging authentication and messaging metadata variables are
only available for the Web Widget and mobile SDK channels.</p>
<p class="p">For more information about setting up messaging authentication, see
<a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4411666638746" target="_blank">Authenticating end users in messaging for the Web Widget and
mobile SDK</a>.</p>
</div>
</div>
<div aria-labelledby="ariaid-title3" class="topic nested1" id="topic_lwy_kmh_twb">
<h2 class="title topictitle2" id="ariaid-title3">Supported messaging metadata variables</h2>
<div class="body">
<div class="p">Unlike other types of AI agent variables, messaging metadata variables have predefined names. You
can’t modify a messaging metadata variable’s name or value in an answer
flow. <table border="1" cellpadding="4" cellspacing="0" class="simpletable" id="topic_lwy_kmh_twb__simpletable_esy_nmh_twb" summary="">
<col style="width:50%">
<col style="width:50%">
<thead>
<tr class="sthead">
<th class="stentry" id="d88e105" style="vertical-align:bottom;text-align:left;"> Messaging metadata variable name </th>
<th class="stentry" id="d88e108" style="vertical-align:bottom;text-align:left;"> Description </th>
</tr>
</thead>
<tbody>
<tr class="strow">
<td class="stentry" headers="d88e105" style="vertical-align:top;"> Provided email </td>
<td class="stentry" headers="d88e108" style="vertical-align:top;"> Email address of the customer. This email address is
pulled from the JWT used for messaging authentication.
</td>
</tr>
<tr class="strow">
<td class="stentry" headers="d88e105" style="vertical-align:top;"> Provided name </td>
<td class="stentry" headers="d88e108" style="vertical-align:top;"> Name of the customer. This name is pulled from the JWT
used for messaging authentication. </td>
</tr>
<tr class="strow">
<td class="stentry" headers="d88e105" style="vertical-align:top;"> Authenticated external ID </td>
<td class="stentry" headers="d88e108" style="vertical-align:top;"> Unique alphanumeric string that identifies the
customer. This ID is pulled from the JWT used for
messaging authentication. </td>
</tr>
<tr class="strow">
<td class="stentry" headers="d88e105" style="vertical-align:top;"> Authenticated status </td>
<td class="stentry" headers="d88e108" style="vertical-align:top;"> If true, the customer is authenticated. Otherwise,
false. This variable is always true or false, never empty.
<p class="p">When using the <strong class="ph b">Authenticated status</strong>
variable in a <strong class="ph b">Branch by condition</strong> step, only
the <strong class="ph b">Is</strong> operator is supported.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div aria-labelledby="ariaid-title4" class="topic nested2" id="topic_byx_dnh_twb">
<h3 class="title topictitle3" id="ariaid-title4">Using the Provided name and Provided email variables</h3>
<div class="body">
<p class="p">Keep the following considerations in mind when using the
<strong class="ph b">Provided name</strong>
and
<strong class="ph b">Provided email</strong>
variables:</p>
<ul class="ul">
<li class="li">Messaging AI agents automatically skip the collection of the <strong class="ph b">Name</strong> and <strong class="ph b">Email</strong>
variables for authenticated customers in an <strong class="ph b">Ask for
details</strong> step. For authenticated customers, these
variables are empty and are skipped in later steps of the
conversation. Instead, use the <strong class="ph b">Provided name</strong> and
<strong class="ph b">Provided email</strong> variables. <div class="p">
<table border="1" cellpadding="4" cellspacing="0" class="simpletable" id="topic_byx_dnh_twb__simpletable_skr_mlz_5wb" summary="">
<col style="width:50%">
<col style="width:50%">
<thead>
<tr class="sthead">
<th class="stentry" id="d88e204" style="vertical-align:bottom;text-align:left;"> Skipped <strong class="ph b">Name</strong> and <strong class="ph b">Email</strong>
variable collection the from <strong class="ph b">Ask for
details</strong> step </th>
<th class="stentry" id="d88e216" style="vertical-align:bottom;text-align:left;">
<strong class="ph b">Provided name</strong> and <strong class="ph b">Provided email</strong>
variables </th>
</tr>
</thead>
<tbody>
<tr class="strow">
<td class="stentry" headers="d88e204" style="vertical-align:top;">
<img class="image img-screenshot" id="topic_byx_dnh_twb__image_fft_jqz_5wb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/fb-skipped-name-email-vars-ask-for-details.png" width="400">
</td>
<td class="stentry" headers="d88e216" style="vertical-align:top;">
<img class="image img-screenshot" id="topic_byx_dnh_twb__image_jnl_clz_5wb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/fb-auth-name-email-vars.png" width="400">
</td>
</tr>
</tbody>
</table>
</div>
</li>
<li class="li">The JWTs used for messaging authentication don't require a customer's name
or email address. If your organization doesn't include a name or email
address in its JWTs, the respective
<strong class="ph b">Provided name</strong>
and
<strong class="ph b">Provided email</strong>
variable are empty and skipped during a
conversation.
<p class="p">In such cases, we recommend updating your JWTs to include a
name and email address.</p>
</li>
<li class="li">The
<strong class="ph b">Provided name</strong>
and
<strong class="ph b">Provided email</strong>
variables are empty
for unauthenticated customers. Avoid using these variables in answer steps
for unauthenticated customers.</li>
</ul>
</div>
</div>
<div aria-labelledby="ariaid-title5" class="topic nested2" id="topic_unt_psh_twb">
<h3 class="title topictitle3" id="ariaid-title5">Using messaging metadata variables with unauthenticated customers</h3>
<div class="body">
<p class="p">If a customer isn't authenticated, the
<strong class="ph b">Authenticated status</strong>
variable's
value is false. Other messaging metadata variables are empty for unauthenticated customers
and are skipped during a conversation.</p>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title6" class="topic nested1" id="topic_jzh_pnh_twb">
<h2 class="title topictitle2" id="ariaid-title6">Best practices for using messaging metadata variables</h2>
<div class="body">
<p class="p">When creating an answer that uses messaging metadata variables, keep the following
best practices in mind:</p>
<ul class="ul" id="topic_jzh_pnh_twb__ul_djd_rnh_twb">
<li class="li">If you don’t include the customer's name or email address in the JWTs used for
messaging authentication, don’t use the
<strong class="ph b">Provided name</strong>
and
<strong class="ph b">Provided email</strong>
variables.</li>
<li class="li">To build an answer flow that’s available to both authenticated and
unauthenticated customers, use a
<strong class="ph b">Branch by condition</strong>
step to
check the customer's
<strong class="ph b">Authenticated Status</strong>
variables. Only include
messaging metadata variables in branches where
<strong class="ph b">Authenticated Status</strong>
is true.</li>
<li class="li">If you’re building an answer that’s only available to authenticated customers
and your organization's JWTs include a name and email address, use the
<strong class="ph b">Provided name</strong>
and
<strong class="ph b">Provided email</strong>
variables for the
customer's name and email address. In such cases, you don’t need to collect this
information again using an
<strong class="ph b">Ask for details</strong>
step.</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/5314129059482",
"url": "https://support.zendesk.com/hc/en-us/articles/5314129059482",
"headline": "Using authentication metadata in an AI agent answer (Legacy)",
"description": "You can customize AI agent responses in messaging by enabling and using predefined messaging metadata variables derived from signed JSON Web Tokens for customer authentication data.",
"articleSection": "Using bot builder to create answers (Legacy)",
"datePublished": "2023-01-16T04:33:45+00:00",
"dateModified": "2026-05-12T16:34:49.527021+00:00",
"inLanguage": "en-US",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/5314129059482"
},
"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>