Creating a Zendesk ticket from an advanced AI agent

What's my plan?

Add-on

AI agents - Advanced

The integration builder can be used to create a Zendesk ticket from a conversation using an AI agent. This article will take you through the steps on how to do so.

For reference, you can find the relevant Zendesk developer documentation on this here.

This article contains the following topics:

• Prerequisites
• Create integration
• Environment and endpoint
• Auth
• Request parameters
• Body
• Chat transcript formatting: Standard vs HTML body
• Standard fields vs Custom field values
• Building in the dialogue builder

Prerequisites

Required to get set up you will need:

• Your Zendesk subdomain
• Your authorization token (see the section below for more information)

Create integration

1. Create a new Integration in API Integrations.
2. Give it a name such as Create Zendesk Ticket and a description.

Environment and endpoint

To access the Zendesk Ticket API, you will need to make a POST request to the following endpoint: http://[your-zendesk-subdomain].zendesk.com/api/v2/tickets

With your Zendesk subdomain, you can construct the endpoint URL to your Zendesk instance. This URL is then used in the Environments section of the integration builder to make the POST request.

1. Navigate to the Environments section of the integration builder.
2. For Method type, select POST.
3. Add your constructed URL endpoint for the Ticket API.
   

Auth

To access the Zendesk API, you will need to create a token in Admin Center.

1. In Admin center, go to Apps and integrations and select APIs > Zendesk API.
   You will see the below screen where you can add a new token.
   
2. Click Add API token.
3. Give it a name such as Create Ticket.
4. Copy the token somewhere safe, as you will need this for setting up the integration in the integration builder.

Once you have these, you can add them to your integration in the integration builder.

1. In the Environment section, click Authorization.
2. In Authorization type, select Basic Auth.
3. Enter an admin email address with /token appended at the end.
4. Paste your created token as the password.
   
5. Make sure to include the authorization token in the request by manually constructing it in the headers.
   

Request Parameters

This is where you will be passing data from the AI agent conversation into the integration to create the ticket.

For the live integration, you will need to set the parameters on your dialogue and then match these to your request parameters in the integration builder. For testing purposes, you can create the request parameters with test values as we are not using live data from a conversation.

Make sure that your request parameter names match those that you have set in your dialogue (via actions). See Building in the dialogue builder for more information.

Body

The body is where you are going to send all of the data from the conversation to create the ticket via the Ticket API. The structure of this body must match the schema for the Ticket API.

To see the schema and which fields can be created with your ticket, see the Zendesk developer documentation here.

Below is an example request body with the request parameters we created earlier.

Test the integration by clicking Test Production.

You should then be able to see your newly created ticket in your Zendesk dashboard.

Chat transcript formatting: Standard vs HTML body

The Ticket API supports either body or html_body for comments. When using body, multiple consecutive spaces are collapsed into a single space and multiple new line (“/n”) characters are collapsed into a single new line. Whereas, when using html_body, you're able to use standard HTML syntax for your comment formatting.

For more information, see the Zendesk developer documentation here.

To use either in your created ticket, you'll structure the one you want to use in “comment” in the request body.

Note: Use either option, not both as in the demonstration below.

If you're sending the chat transcript from the conversation, then it's recommended that you use the reformat values tool to make the transcript more readable. Rather than just being one big chunk of text, you can add line breaks for the beginning of each message. 

If you're sending an HTML body, then you can use the Reformat values tool to add your HTML.

For instructions on how to use the Reformat values tool, see Reformatting values in request parameters for advanced AI agents.

In the screenshot below, we've reformatted the chat transcript to make clickable URLs and added line breaks with <br>.

Standard fields vs Custom field values

In addition to the standard fields that can be created and sent in the body of the request, you can also create custom field values. For instructions on how to set up custom fields in the body, see the Zendesk developer documentation here.

Building in the Dialogue Builder

1. Add the API Node and select the Create Zendesk Ticket integration that you created above.
2. Create an action on the API node which sets the parameters from the conversation.
   It will look something like this:
   
3. Add a message for the Success and Fallback scenarios.