Creating custom actions for auto assist, AI agents, and action flows

<body>
<p id="docs-hc-snippet" style="display: none;">Custom actions are automated tasks that you configure. They can be carried out byauto assist, which is part ofagent copilot, byAI agents, and byaction flows, which perform a pre-defined series of automated actions.</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_gpee">
<table>
<tbody>
<tr>
<td>
<strong>All Suites</strong>
</td>
<td>Growth, Professional, Enterprise, or Enterprise Plus</td>
</tr>
</tbody>
</table>
</div>

</div>

<div class="body">

<p class="p">Custom actions are automated tasks that you configure. They can be carried out by <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/7051314237466" target="_blank">auto assist</a>, which is part of <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/7908817636378" target="_blank">agent copilot</a>, by <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/6970583409690" target="_blank">AI agents</a>, and by <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/8855513857306" target="_blank">action flows</a>, which perform a pre-defined series of
automated actions.</p>
<p class="p">This article contains the following topics: </p>
<ul class="ul" id="zug_ai_auto_assist_actions__ul_l55_w5n_xcc">
<li class="li"><a class="xref" href="#topic_gyz_55n_xcc">Best practices for creating custom actions</a></li>
<li class="li"><a class="xref" href="#topic_lp5_s5n_xcc">Creating a custom action</a></li>
<li class="li"><a class="xref" href="#topic_bxm_t5n_xcc">Testing an action</a></li>
<li class="li"><a class="xref" href="#topic_ynl_w5r_1fc">Next steps</a></li>
</ul>
<p class="p">Related articles: </p>
<ul class="ul" id="zug_ai_auto_assist_actions__ul_s31_fvn_xcc">
<li class="li"><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/9174548349978" target="_blank">About actions for auto assist and action
flows</a></li>
<li class="li"><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/9156980948250" target="_blank">Managing actions for auto assist and action
flows</a></li>
</ul>
</div>
<div aria-labelledby="ariaid-title2" class="topic nested1" id="topic_gyz_55n_xcc">
<h2 class="title topictitle2" id="ariaid-title2">Best practices for creating custom actions</h2>
<div class="body">
<p class="p">When creating custom actions, follow these best practices: </p>
<ul class="ul" id="topic_gyz_55n_xcc__ul_ekg_5j4_xcc">
<li class="li">
<strong class="ph b">Use connections for authentication.</strong> Don’t include authentication
credentials in your custom action configuration. <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5040378297626" target="_blank">Use a connection</a> instead, which are
purpose-built to keep your sensitive details safe. </li>
<li class="li">
<strong class="ph b">Be mindful of access privileges.</strong> Keep in mind that a connection might
have higher access privileges than your agents or end users. Configure your
custom actions, <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/7924047699738" target="_blank">procedures</a>, and agent training to
avoid sharing sensitive data to the wrong audience. </li>
<li class="li">
<strong class="ph b">Keep your data as private as possible.</strong> When capturing parts of a custom
action’s response as outputs, be mindful of only capturing the specific data
points you need. Capturing data that isn’t directly relevant to the task at hand
isn’t good privacy practice, and furthermore could confuse auto assist. </li>
<li class="li">
<strong class="ph b">Write good names and descriptions for custom actions, inputs, and
outputs.</strong> Names and descriptions help auto assist determine when custom
actions (including their inputs and outputs) are relevant to a customer request.
Additionally, if you make changes to an existing custom action, make sure that
the name and description are still accurate.<p class="p">Names and descriptions must
clearly describe the meaning and outcome of a custom action. For example:
</p>
<ul class="ul" id="topic_gyz_55n_xcc__ul_iww_33b_ycc">
<li class="li">Custom action name: Add book to cart </li>
<li class="li">Custom action description: Adds a book to the customer's shopping
cart.</li>
</ul>
<p class="p">When referencing custom actions in auto assist procedures, remember to
use similar language to invoke a particular action. </p>
<ul class="ul" id="topic_gyz_55n_xcc__ul_zyp_33b_ycc">
<li class="li">For example: “After the customer has confirmed the book they want to
purchase, add that book to their cart.” </li>
</ul>
</li>
<li class="li">
<strong class="ph b">Plan for missing inputs.</strong> If an input will be available only sometimes,
make sure your description explains how that situation should be handled. For
example, not every requester will have an email address. So your description for
an input named <em class="ph i">requester_email_address</em> might say, "The email address of
the end user who initiated the ticket. If this isn't available, use 'not
available.'"</li>
<li class="li">
<strong class="ph b">Clearly differentiate your names and descriptions for custom action and
action flows.</strong> If you're using both custom actions and action flows, it's
important that the names you use for each are clearly differentiated. While
custom actions and action flows are managed in separate parts of Admin Center,
AI agents and auto assist still see both and consider them to be
equivalent.<p class="p">For example, if you have a custom action named "order refund"
and an action flow named "refund order", the descriptions need to be
detailed enough to differentiate them. If they both have vague descriptions,
the AI agent or auto assist might use the wrong one or pick both.</p>
</li>
</ul>
</div>
<div aria-labelledby="ariaid-title3" class="topic nested2" id="topic_l25_5h4_xcc">
<h3 class="title topictitle3" id="ariaid-title3">Limits for custom actions</h3>
<div class="body">
<p class="p">The following limits apply to custom actions: </p>
<ul class="ul" id="topic_l25_5h4_xcc__ul_qgm_xh4_xcc">
<li class="li">You can have a maximum of 100 custom actions per account. </li>
<li class="li">Each custom action has a maximum of 100 inputs and 100 outputs. </li>
<li class="li">Custom actions have a timeout of 10 seconds. If the external system takes
longer than 10 seconds to respond, or that response fails to be received by
your Zendesk account, the action isn't performed. </li>
<li class="li">Custom actions have a maximum response size of 2MB.</li>
<li class="li">Custom actions created before March 13, 2025 aren't available as steps in
action flows until they've been updated and saved. </li>
</ul>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title4" class="topic nested1" id="topic_lp5_s5n_xcc">
<h2 class="title topictitle2" id="ariaid-title4">Creating a custom action</h2>
<div class="body">
<div class="p">Admins can create custom actions in Admin Center. Custom actions connect to external
systems and require the following information: <ul class="ul" id="topic_lp5_s5n_xcc__ul_jpp_zh4_xcc">
<li class="li">
<strong class="ph b">Input</strong>: The information that an action uses in order to run. Each
input you define creates an input placeholder, which can be inserted into
the URL, body, query parameters, or headers of your action.<p class="p">Auto assist
replaces these placeholders with data when it executes the action. In
action flows, the placeholders can be used in various properties of
action flow steps.</p>
</li>
<li class="li">
<strong class="ph b">API call</strong>: How, exactly, the information should be structured when
it’s sent to the API. </li>
<li class="li">
<strong class="ph b">Output</strong>: Determines how Zendesk should interpret the data returned by
the API. The outputs you define tell the action which parts of the API
response to send back to auto assist when the action is executed.</li>
</ul>
</div>
<p class="p"><strong class="ph b">To create a custom action</strong></p>
<div class="p">
<ol class="ol" id="topic_lp5_s5n_xcc__ol_m2c_b34_xcc">
<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" 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">Actions &gt; Custom
actions</strong>.</span></li>
<li class="li">Click <strong class="ph b">Create custom action</strong>. </li>
<li class="li">In the <strong class="ph b">Name</strong> field, enter a descriptive name for your custom action.
<p class="p">This name appears to agents and in the event log.</p>
</li>
<li class="li">In the <strong class="ph b">Description</strong> field, enter a description of the action.<p class="p">This
description is used by the system to determine when the custom action
should be used with <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/7051314237466" target="_blank">auto assist</a>. For help writing
good descriptions, see <a class="xref" href="#topic_gyz_55n_xcc">Best practices for creating custom actions</a>.</p>
</li>
<li class="li">In the <strong class="ph b">Inputs</strong> section, click <strong class="ph b">Add input</strong>. <ol class="ol" id="topic_lp5_s5n_xcc__ol_apx_334_xcc" type="a">
<li class="li">In the <strong class="ph b">Add input</strong> window, provide the following information:
<ul class="ul" id="topic_lp5_s5n_xcc__ol_rfs_j34_xcc">
<li class="li">
<strong class="ph b">Name</strong>: Enter a descriptive name for the input. </li>
<li class="li">
<strong class="ph b">Description</strong>: Enter a description of the input. </li>
<li class="li">
<strong class="ph b">Type</strong>: Select from the following options:
<strong class="ph b">String</strong>, <strong class="ph b">Integer</strong>, <strong class="ph b">Decimal</strong>,
<strong class="ph b">Boolean</strong>, <strong class="ph b">Date</strong>, <strong class="ph b">Datetime</strong>, or an
<strong class="ph b">Array</strong> of the supported data types.<div class="note attention" id="topic_lp5_s5n_xcc__note_sw2_k34_xcc">
<span class="attentiontitle"></span> Input types are
strictly enforced. For example, 3.0 isn't accepted as an
integer, the string “true” isn't accepted as a boolean,
and the boolean value false isn't accepted as a
string.</div>
</li>
</ul>
</li>
<li class="li">Click <strong class="ph b">Add input</strong>. </li>
</ol>
</li>
<li class="li">In the <strong class="ph b">API configuration</strong> panel, provide the following information:
<ol class="ol" id="topic_lp5_s5n_xcc__ol_yvg_n34_xcc" type="a">
<li class="li">
<strong class="ph b">Request method</strong>: Select <strong class="ph b">GET</strong>, <strong class="ph b">POST</strong>, <strong class="ph b">PATCH</strong>,
<strong class="ph b">PUT</strong>, or <strong class="ph b">DELETE</strong>, depending on what you want your
action to do. </li>
<li class="li">
<strong class="ph b">Endpoint URL</strong>: Enter the URL of your external service. <p class="p">Only
<code class="ph codeph">https://</code> URLS are allowed.</p>
</li>
<li class="li">
<strong class="ph b">Authentication</strong>: Select an existing <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5040378297626" target="_blank">API connection</a>. <p class="p">To
connect to a Zendesk API, see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5040378297626#topic_tp5_gp5_kkc" target="_blank">Creating custom connections
to Zendesk APIs</a>.</p>
</li>
<li class="li">
<strong class="ph b">Body</strong>: Enter the information that you’re requesting in this
API call. <p class="p">To insert placeholders for any of the inputs you
created, click <strong class="ph b">{+}</strong> and select the appropriate
input.</p>
</li>
<li class="li">
<strong class="ph b">Query parameters</strong>: Click <strong class="ph b">Add parameter</strong> and add a
<strong class="ph b">Key</strong> and <strong class="ph b">Value</strong> for any parameters that apply to
this API call. </li>
<li class="li">
<strong class="ph b">Headers</strong>: Click <strong class="ph b">Add header</strong> and add a <strong class="ph b">Name</strong> and
<strong class="ph b">Value</strong> for any headers that apply to this API call. <p class="p">You
don’t need to add a content-type header. Only the
application/json value is supported, and this header is
automatically added when the API call is made.</p>
<p class="p">If you
specify an accept header, use the format
<code class="ph codeph">application/{{subtype}}+json</code>, where
<code class="ph codeph">{{subtype}}</code> is replaced with the system you
want to connect to. For example, to connect with Recurly, you'd
specify
<code class="ph codeph">application/vnd.recurly.v2021-02-25+json</code>.
If you don't specify an accept header, this header is
automatically added with the <code class="ph codeph">application/json</code>
value.</p>
</li>
</ol>
</li>
<li class="li">In the <strong class="ph b">Outputs</strong> section, click <strong class="ph b">Add output</strong>. <ol class="ol" id="topic_lp5_s5n_xcc__ol_dhn_t34_xcc" type="a">
<li class="li">In the <strong class="ph b">Add outputs</strong> window, enter test data for each of the
inputs you configured. </li>
<li class="li">Click <strong class="ph b">Make API call</strong>.<p class="p">This information is sent to your
external service, which returns a representative response.
</p>
<div class="note" id="topic_lp5_s5n_xcc__note_rr3_534_xcc">
<span class="notetitle">Note:</span> When an external action runs,
the response must be JSON and must have the appropriate JSON
header (content-type: application/json). Other JSON-compatible
content types aren’t currently supported (for example,
vnd.oracle.resource+json or vnd.api+json).</div>
</li>
<li class="li">On the <strong class="ph b">Output</strong> tab, find the appropriate output from the
response and click <strong class="ph b">Add</strong>.<p class="p">You can click the <strong class="ph b">Response
body</strong> tab to see how the actual response is
formatted.</p>
</li>
<li class="li">Enter a <strong class="ph b">Name</strong> and <strong class="ph b">Description</strong> for the output, then
click <strong class="ph b">Add output</strong>.</li>
<li class="li">Repeat as required to capture all the outputs you want to return to
auto assist.</li>
<li class="li">Click <strong class="ph b">Done</strong>.<p class="p">If a mapped output isn’t included in the
response when an action is executed, the action still succeeds,
but the output’s key is omitted from the response sent back to
auto assist.</p>
</li>
</ol>
</li>
<li class="li">Click <strong class="ph b">Save</strong>. </li>
</ol>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title5" class="topic nested1" id="topic_bxm_t5n_xcc">
<h2 class="title topictitle2" id="ariaid-title5">Testing an action</h2>
<div class="body">
<p class="p">When you create a custom action, you should test it to make sure it behaves as you
expect. If necessary, run multiple tests with different input values that yield
different responses to test all possible outputs. </p>
<p class="p"><strong class="ph b">To test an action</strong></p>
<div class="p">
<ol class="ol" id="topic_bxm_t5n_xcc__ol_wpg_1j4_xcc">
<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" 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">Actions &gt; Custom
actions</strong>.</span></li>
<li class="li">For the custom action you want to edit, click the options menu (<img class="image" height="16" id="topic_bxm_t5n_xcc__image_hm4_cj4_xcc" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/sell_icon_menu_vertical.png" width="16">) and select <strong class="ph b">Test</strong>. </li>
<li class="li">In the <strong class="ph b">Inputs</strong> section of the <strong class="ph b">Test</strong> tab, enter test data for
each of the inputs you configured. </li>
<li class="li">Click <strong class="ph b">Make API</strong> call. <p class="p">This sends information to the external
service your custom action is connected to and returns a representative
response. </p>
</li>
<li class="li">In the <strong class="ph b">Outputs</strong> section, verify that the response includes the
information you expect. </li>
</ol>
</div>
<p class="p">If you encounter issues during testing, here are some troubleshooting
recommendations: </p>
<ul class="ul" id="topic_bxm_t5n_xcc__ul_q25_hj4_xcc">
<li class="li">Because custom actions are connected to external systems, the external system's
documentation is the best source for detailed troubleshooting. </li>
<li class="li">For an overview of HTTP error codes that you might encounter during testing, see
<a class="xref" href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status" target="_blank">HTTP response status codes</a>. </li>
<li class="li">Ensure that all inputs and outputs are the correct data type (integer, decimal,
string, or boolean) for your use case.</li>
<li class="li">You can see more details about the custom action execution in the <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408819871130" target="_blank">integration log</a>.</li>
</ul>
</div>
</div>
<div aria-labelledby="ariaid-title6" class="topic nested1" id="topic_ynl_w5r_1fc">
<h2 class="title topictitle2" id="ariaid-title6">Next steps</h2>
<div class="body">
<div class="p">After creating and testing an action, you can do the following:<ul class="ul" id="topic_ynl_w5r_1fc__ul_g1x_f4r_1fc">
<li class="li"><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/7924047699738#topic_vs3_j44_xcc" target="_blank">Insert the action when creating auto
assist procedures</a></li>
<li class="li"><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/10783053154202#topic_ufn_3ll_hjc" target="_blank">Add the action to a dialogue or
generative procedure in an AI agent</a></li>
<li class="li"><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/8855601898266" target="_blank">Add the action as a step when creating
action flows</a></li>
<li class="li"><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/9156980948250" target="_blank">Manage your custom actions</a></li>
</ul>
</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/8013439366810-Creating-custom-actions-for-auto-assist-AI-agents-and-action-flows",
"url": "https://support.zendesk.com/hc/en-us/articles/8013439366810-Creating-custom-actions-for-auto-assist-AI-agents-and-action-flows",
"headline": "Creating custom actions for auto assist, AI agents, and action flows",
"description": "You can create, configure, test, and manage custom automated actions that connect to external systems for use with auto assist, AI agents, and action flows, following best practices and system limits.",
"articleSection": "Providing AI assistance with auto assist",
"datePublished": "2024-09-13T16:32:35+00:00",
"dateModified": "2026-08-31T18:09:14.580316+00:00",
"inLanguage": "en-US",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/8013439366810-Creating-custom-actions-for-auto-assist-AI-agents-and-action-flows"
},
"author": {
"@type": "Organization",
"name": "Zendesk",
"url": "https://www.zendesk.com"
},
"publisher": {
"@type": "Organization",
"name": "Zendesk"
},
"isPartOf": {
"@type": "WebSite",
"name": "Zendesk Help",
"url": "https://support.zendesk.com/hc/en-us"
},
"about": {
"@type": "SoftwareApplication",
"name": "Zendesk"
}
}</script>
</body>