Creating actions for auto assist and action flows

What's my plan?

Suite

Growth, Professional, Enterprise, or Enterprise Plus

Actions are automated tasks that you configure. They can be carried out by auto assist, which is part of agent copilot, and by action flows, which perform a pre-defined series of automated tasks.

This article contains the following topics:

• Best practices for creating actions
• Creating an external action
• Testing an action
• Next steps

Related articles:

• About actions for auto assist and action flows
• Managing actions for auto assist and action flows

Best practices for creating actions

When creating actions, follow these best practices:

• Use connections for authentication. Don’t include authentication credentials in your action configuration. Use a connection instead, as these are purpose-built to keep your sensitive details safe.
• Be mindful of access privileges. Keep in mind that a connection might have higher access privileges than your agents or end users. Configure your actions, procedures, and agent training to avoid sharing sensitive data to the wrong audience.
• Keep your data as private as possible. When capturing parts of an 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.
• Write good names and descriptions for actions, inputs, and outputs. Names and descriptions help auto assist determine when actions (including their inputs and outputs) are relevant to a customer request. Additionally, if you make changes to an existing action, make sure that the name and description are still accurate.

  Names and descriptions must clearly describe the meaning and outcome of an action. For example:

  • Action name: Add book to cart
  • Action description: Adds a book to the customer's shopping cart.

  When referencing actions in auto assist procedures, remember to use similar language to invoke a particular action.

  • For example: “After the customer has confirmed the book they want to purchase, add that book to their cart.”
• Plan for missing inputs. 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 requester_email_address might say, "The email address of the end user who initiated the ticket. If this isn't available, use 'not available.'"
• Clearly differentiate your action and action flow names and descriptions If you're using both actions and action flows, it's important that the names you use for each are clearly differentiated. While actions and action flows are managed in separate parts of Admin Center, auto assist still sees both and considers them to be equivalent.

  For example, if you have an 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, auto assist might suggest the wrong one or pick both.

Limits for actions

The following limits apply to actions:

• You can have a maximum of 100 actions per account.
• Each action has a maximum of 100 inputs and 100 outputs.
• External 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 is not performed.
• External actions have a maximum response size of 2MB.
• Actions created before March 13, 2025 aren't available as steps in action flows until they've been updated and saved.

Creating an external action

Admins can create new external actions in Admin Center. External actions require an input, an API call, and an output.

• The input is 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.

  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.

• The API call is how exactly the information should be structured when it’s sent to the API.
• The output 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.

To create an external action

1. In Admin Center, click Apps and integrations in the sidebar, then select Actions > Actions.
2. Click Create action.
3. In the Name field, enter a descriptive name for your action.

   This name appears to agents and in the event log.

4. In the Description field, enter a description of the action.

   This description is used by the system to determine when the action should be used with auto assist. For help writing good descriptions, see Best practices for creating actions.

5. In the Inputs section, click Add input.
   1. In the Add input window, fill in the following fields:
      • Name: Enter a descriptive name for the input.
      • Description: Enter a description of the input.
      • Type: Select from the following options: String, Integer, Decimal, or Boolean.
        Input types are strictly enforced. For example, 3.0 will not be accepted as an integer, the string “true” will not be accepted as a boolean, and the boolean value false will not be accepted as a string.
   2. Click Add input.
6. In the API configuration panel, fill in the following fields:
   1. Request method: Select GET, POST, PATCH, PUT, or DELETE, depending on what you want your action to do.
   2. Endpoint URL: Enter the URL of your external service.

      Only https:// URLS are allowed.

   3. Authentication: Select an existing API connection.
   4. Body: Enter the information that you’re requesting in this API call.

      To insert placeholders for any of the inputs you created, click {+} and select the appropriate input.

   5. Query parameters: Click Add parameter and add a Key and Value for any parameters that apply to this API call.
   6. Headers: Click Add header and add a Name and Value for any headers that apply to this API call.

      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.

7. In the Outputs section, click Add output.
   1. In the Add outputs window, enter test data for each of the inputs you configured.
   2. Click Make API call.

      This information is sent to your external service, which returns a representative response.

      Note: 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).
   3. On the Output tab, find the appropriate output from the response and click Add.

      You can click the Response body tab to see how the actual response is formatted.

   4. Enter a Name and Description for the output, then click Add output.
   5. Repeat as required to capture all the outputs you want to return to auto assist.
   6. Click Done.

      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.

8. Click Save.

Testing an action

When you create an 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.

To test an action

1. In Admin Center, click Apps and integrations in the sidebar, then select Actions > Actions.
2. For the action you want to edit, click the options menu () and select Test.
3. In the Inputs section of the Test tab, enter test data for each of the inputs you configured.
4. Click Make API call.

   This information is sent to your external service, which returns a representative response.

5. In the Outputs section, verify that the response includes the information you expect.

If you encounter issues during testing, here are some troubleshooting recommendations:

• If you’re using an external action to interact with an external system, that product’s documentation is the best source for detailed troubleshooting.
• For an overview of HTTP error codes that you might encounter during testing, see HTTP response status codes.
• Ensure that all inputs and outputs are the correct data type (integer, decimal, string, or boolean) for your use case.
• You can see more details about the action execution in the integration log.

Next steps

After creating and testing an action, you can do the following:

• Insert the action when creating auto assist procedures
• Add the action as a step when creating action flows
• Manage your custom actions