Reformatting values in request parameters for AI agents

<div class="article-banners">
<div id="docs-wmp-link"><a href="https://support.zendesk.com/hc/en-us/articles/5411234991258-plan" rel="noopener noreferrer" target="_blank">What's my plan?</a></div>
<div class="article-banner" id="suite_all"><figure class="wysiwyg-table wysiwyg-table-align-left"><table><tbody><tr>
<td><strong>All Suites</strong></td>
<td>Team, Growth, Professional, Enterprise, or Enterprise Plus</td>
</tr></tbody></table></figure></div>
<div class="article-banner" id="support_all"><figure class="wysiwyg-table wysiwyg-table-align-left"><table><tbody><tr>
<td><strong>Support</strong></td>
<td>Team, Professional, or Enterprise</td>
</tr></tbody></table></figure></div>
</div><div class="body">

<p>In the <a href="https://support.zendesk.com/hc/en-us/articles/8357756844442">integration builder</a>, request parameters allow you to pull data (conversation parameters) from AI agent conversations and pass it to external endpoints. In some cases, you may need to transform or reformat this data before sending it in an API request as either a URL query or in the request body. To do this, you can use JSONata, a powerful query and transformation language.</p>
<p>This article contains the following topics:</p>
<ul>
<li data-list-item-id="e6591a79de60b5934a18a5819e90ee522"><a href="#h_01JFB2S65WMQX70ZV1EZYNPQN1">Reformatting the value of a request parameter</a></li>
<li data-list-item-id="ecb5b1067a0a0d53cb162ea0bf4ebc1b5"><a href="#h_01JFB2SHX43ED9QVH5MVFD6441">Common use case examples for reformatting values</a></li>
</ul>
<p>Related articles:</p>
<ul><li data-list-item-id="e4863eb395cb8bcafb4877ed41f62072b"><a href="https://support.zendesk.com/hc/en-us/articles/8498753675290">Integration builder resources</a></li></ul>
<h2 id="h_01JFB2S65WMQX70ZV1EZYNPQN1">Reformatting the value of a request parameter</h2>
<p>You can reformat a request parameter’s value using JSONata.</p>
<p><strong>To reformat the value of a request parameter</strong></p>
<ol>
<li data-list-item-id="ed821a67b1c7bf2206d2fe99c40e9d04f">In the AI agents workspace, in the top-right corner, use the AI agent drop-down field to select your AI agent.</li>
<li data-list-item-id="e42b0563039bfe4cb1b95515e5c1d6f1b">In the main menu on the left, click <strong>API integrations</strong>.</li>
<li data-list-item-id="eb5956175d9edfee5c636f3669e7d6e1b">Select or create an integration.</li>
<li data-list-item-id="e75e407c0dcaf15bb9f54896a7d1584e9">On the <strong>Request parameters</strong> page, select or create the request parameter you want to reformat the value for.</li>
<li data-list-item-id="e0aea376733bf385cc1a42c29085f4925">In the <strong>Test value</strong> field, select the <strong>Reformat value</strong> icon (<img src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ultimate_reformat_value_icon.png">).<br><img src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ultimate_reformatting_values_1.png">
</li>
<li data-list-item-id="e4026ae4775756d15ec7450dc4346d4a2">In the <strong>Reformat value</strong> dialog, in the <strong>Reformatting JSONata</strong> field, use JSONata to transform or reformat the value associated with the selected request parameter key.<br>In your JSONata query, use <strong>'$'</strong> to represent the key whose value you’re reformatting.<br>The <strong>Test value preview</strong> field gives you a way to check the results of your query in real time.<br><img src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ultimate_reformatting_values_2.png" width="400">
</li>
<li data-list-item-id="e1c6bc8507ba9504642ec6f352e976ef8">Click <strong>Done</strong>.</li>
<li data-list-item-id="e882fcb36ce4395b519369ca8b460fb88">(Optional) If you’re adding the request parameter to the body of an API request:<ol>
<li data-list-item-id="ec5bb70715217d8c34ff596308e46bc54">Under the <strong>Environment header</strong> on the left, select the appropriate environment.</li>
<li data-list-item-id="e44ea543985aa415b364aa691ea8eb769">Select the <strong>Body</strong> tab.</li>
<li data-list-item-id="e39796f0f9a5fd474057f51788aae2099">Add your JSON object, using the request parameter as a value in double curly brackets.<br><img src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ultimate_reformatting_values_3.png" width="600">
</li>
</ol>
</li>
</ol>
<h2 id="h_01JFB2SHX43ED9QVH5MVFD6441">Common use cases for reformatting values</h2>
<p>Within the integration builder, you can define request parameters by assigning them to specific keys. While these values may work as is, there are scenarios where they need to be transformed or reformatted to match the requirements of the external system.</p>
<p>For example, you might want to:</p>
<ul>
<li data-list-item-id="ed372583642310d558370a1890dffde09">
<strong>Reformat dates</strong>: Change the format of a date from MM/DD/YYYY to YYYY-MM-DD or ISO 8601 to match API requirements.</li>
<li data-list-item-id="e0ca24ce34661905551148d06cf524dc7">
<strong>Perform string operations</strong>: Manipulate strings, such as adding or removing characters, combining multiple fields, or transforming strings to contain HTML.</li>
<li data-list-item-id="e392e7df35b9c5222c9acbb86ddeb50ee">
<strong>Apply conditional logic</strong>: Apply conditions, such as checking whether a field is empty or assigning a default value if needed.</li>
</ul>
<p>This section contains the following examples:</p>
<ul>
<li data-list-item-id="e6c0311a039b5e3609aea5644c39d0d82"><a href="#h_01JFB4304S6T2GAD4NXXRJHNP4">Scenario: Reformatting dates</a></li>
<li data-list-item-id="e8fea65fc696f64d4b48a0e421a48e24f"><a href="#h_01JFB45K9TSRJC0G8S6MD157AD">Scenario: Reformatting URLs to make links clickable</a></li>
<li data-list-item-id="e11814e29997673dd10a0128bd983af19"><a href="#h_01JFB43M0FJW3RQG80KDDSVRSN">Scenario: Reformatting a chat transcript to make it more readable</a></li>
</ul>
<h3 id="h_01JFB4304S6T2GAD4NXXRJHNP4">Scenario: Reformatting dates</h3>
<p>In this scenario, your endpoint needs to check a date formatted as YYYY-MM-DD or in an ISO 8601 format. However, for your conversation, you want dates displayed in a more user-friendly format of DD/MM/YYYY.</p>
<p>Here’s the JSONata query you would use in this scenario:</p>
<pre class="wysiwyg-code-block"><code class="language-auto">$substring($, 6, 10) &amp; "-" &amp; $substring($, 3, 2) &amp; "-" &amp; $substring($, 0, 2)</code></pre>
<p><img src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ultimate_reformatting_values_4.png" width="400"></p>
<h3 id="h_01JFB45K9TSRJC0G8S6MD157AD">Scenario: Reformatting URLs to make links clickable</h3>
<p>In this scenario, you want to convert URLs into clickable links by searching for text (a substring) that starts with http:// or https:// followed by a number of non-whitespace characters. You then want to replace that substring using the JSONata $replace function, with a string that wraps the matched URL in an HTML &lt;a&gt; tag, creating a clickable link.</p>
<p>Here’s the JSONata query you would use in this scenario:</p>
<pre class="wysiwyg-code-block"><code class="language-auto">(
$text := "Chat transcript unavailable. Here is a link:https://www.zendesk.com. Here is another link: https://www.w3schools.com.";

$replace($text, /(https?:\/\/[^\s]+)/, '&lt;a href="$1"&gt;$1&lt;/a&gt;'
)</code></pre>
<p><img src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ultimate_reformatting_values_5.png" width="400"></p>
<h3 id="h_01JFB43M0FJW3RQG80KDDSVRSN">Scenario: Reformatting a chat transcript to make it more readable</h3>
<p>In this scenario, you want to add a chat transcript to a ticket. However, in its default form, the chat transcript is not very readable:</p>
<ul><li data-list-item-id="e0be7dd2483ce632a2935419a3711aaea">Chat Transcript - 2024-10-12 (13:04:10) AI agent: Welcome to the customer engineering AI agent! (13:04:10) AI agent: Choose which integration to test: (13:04:10) Visitor: test c.id: d501304d-da09-4485-a4c7-1c708ec0005d All times in UTC</li></ul>
<p>You want to transform it into a more user-friendly format by breaking each message onto a new line. Because each new message starts with an open parenthesis ( ( ) , you can use JSONata to replace each occurrence of ( with a line break followed by the (.</p>
<p>The reformatted conversation would then look like this:</p>
<ul><li data-list-item-id="ebc034c2d418255efaa36714e6fb90ef3">Chat Transcript - 2024-10-12<br>(13:04:10) AI agent: Welcome to the Integration Builder AI agent!<br>(13:04:10) AI agent: Choose which integration to test:<br>(13:04:10) Visitor: test c.id: d501304d-da09-4485-a4c7-1c708ec0005d All times in UTC</li></ul>
<p>Here’s the JSONata query you would use in this scenario:</p>
<pre class="wysiwyg-code-block"><code class="language-auto">$replace($, “(“, “\n(“)</code></pre>
<p><img src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ultimate_reformatting_values_6.png" width="400"></p>
<p>Additionally, you’d need to add this parameter to the the body section in your environment so that it’s sent with the request:</p>
<pre class="wysiwyg-code-block"><code class="language-auto">{
"chatTranscript": "{{chatTranscript}}"
}</code></pre>
<p> </p>
<script id="docs-schema-markup" type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "TechArticle",
"@id": "https://support.zendesk.com/hc/en-us/articles/8560203369242",
"url": "https://support.zendesk.com/hc/en-us/articles/8560203369242-Reformatting-values-in-request-parameters-for-advanced-AI-agents",
"headline": "Reformatting values in request parameters for advanced AI agents",
"description": "You can use JSONata within the integration builder to transform or reformat request parameter values before sending them in API requests to external endpoints.",
"articleSection": "Integrating other platforms with advanced AI agents",
"datePublished": "2024-12-17T20:14:22+00:00",
"dateModified": "2025-09-05T23:12:23+00:00",
"inLanguage": "en-US",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/8560203369242"
},
"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",
"softwareAddOn": {
"@type": "SoftwareApplication",
"name": "AI agents",
"@id": "https://support.zendesk.com/hc/en-us/sections/8988994355994"
}
}
}
</script>
</div>