Creating a custom action

Custom actions live in Admin Center, not in the AI agent, and one definition serves auto assist, AI agents and action flows.

Connecting an AI agent to one of your systems. Two things are not where people look for them: custom actions live in Admin Center rather than inside the AI agent, and one definition serves auto assist, AI agents and action flows alike.

Create one

1. In Admin Center, click Apps and integrations, then select Actions and Custom actions.
2. Click Create custom action and give it a Name and a Description.
3. Add each Input with a Name, a Description and a Type: String, Integer, Decimal, Boolean, Date, Datetime or Array.
4. Set the Request method and the Endpoint URL. Only https:// is allowed, and the endpoint has to answer with JSON and the header content-type: application/json. An endpoint that looks fine in a browser but sends something else fails here without saying why.
5. Under Authentication, select an existing API connection.
6. Add Query parameters, Headers and a Body as needed. Use the {+} button to insert your inputs into the body.
7. Define each Output with a Name and a Description, then test it, including the failures.

The limits, which shape the design

The ten-second timeout is the one that decides architecture. An action that queries a slow back office will not survive it, and the answer is a faster endpoint rather than a longer conversation.

If you have actions built before 13 March 2025, they need updating before they can be used in action flows.

Describe it for the system, not for you

The Description is what the system uses to decide when the action should be used. "Looks up the status and expected delivery date of an order by order number" is usable. "Order API v2" is not.

Ask for the minimum

Every input is something the customer must supply before anything happens. An action needing three pieces of information will often not complete, because people abandon at the second question.

Return what the reply needs

Define outputs for the fields you will use, not the whole record. A hundred outputs are allowed; three make the reply predictable and keep data out of the conversation that did not need to be there.

Credentials belong in a connection

Zendesk is explicit: do not put authentication credentials in the custom action configuration, and use a connection instead, because connections are built to hold that safely. Scope the account behind it to exactly what the action does, so a mistake cannot reach further than intended.

Failures are the design

System unavailable, nothing found, ambiguous match, permission denied, and the timeout above. Each needs a defined outcome, and "hand over to a person" is a perfectly good one. An action without failure handling produces conversations that stop mid-sentence.

Test before it exists in a conversation

Verify the call on its own first. Debugging an action inside a live exchange means two systems and a language model between you and the fault.

See also

• Testing actions
• Managing actions
• What actions are and what an AI agent can do with them