> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/docs/handoffs/zendesk/zendesk-ticketing/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Zendesk Ticketing

## Overview\[#overview]

The Zendesk Ticketing app enables end users to create email support requests that are sent to your Zendesk Support team as [Handoff](/docs/handoffs) tickets. This integration gives you control over the information shared with your Zendesk Support environment and allows you to customize tickets directly from your AI Agent.

## Capabilities & configuration

The Zendesk Ticketing [Handoff](/docs/handoffs) provides the following capabilities for creating and customizing support tickets.

### Email channel threading

When using the Zendesk Ticketing block for Email channel Handoffs, you can configure the [SMTP Connector](/docs/handoffs/zendesk/zendesk-smtp-connector) to allow human agent replies to continue in the same email thread as the original end-user conversation. This provides a more consistent experience for end users and reduces confusion caused by broken or split threads.

* **With the SMTP Connector configured**: Human agents can reply from the same BYOD address as the AI Agent, and replies continue in the same email thread.
* **Without the SMTP Connector**: Human agents must use a different email address than the BYOD address configured for the AI Agent. Replies to escalated conversations are sent in a separate email thread.

> **Note**
>
> If the **Ticket Recipient** optional input field is set to a different email address than the BYOD address used by the AI Agent, and you expect human agents to reply from that address in the same thread, you must configure the SMTP Connector for both addresses. Both addresses must be on the same domain (for example, `taxes@example.com` and `legal@example.com`). Addresses on different domains are not supported for same-thread behavior.

### Ticket customizations

The Zendesk Ticketing app supports the following ticket customizations:

* Set the ticket Subject
* Set the Request Type
* Update the Ticket Status

### How a Zendesk Ticketing Handoff works\[#how-a-zendesk-ticketing-handoff-works-in-ada]

The primary goal of a ticketing [Handoff](/docs/handoffs) is to collect information from the end user to share with your support team. You need to capture the end user's contact information and their issue details. Once this is done, the Zendesk Ticketing app can complete the process by sharing that information with your Zendesk environment.

The Zendesk Ticketing app is a passive block. This means that it does not capture any data from the end user by itself. Any end user information you wish to pass to your Zendesk environment using the Zendesk Ticketing app must be collected separately as variables.

The following blocks are necessary to build a Zendesk Ticketing Handoff.

#### Capture blocks\[#capture-blocks]

[Capture blocks](/docs/handoffs/handoff-management/blocks/capture-block) capture information directly from the end user and save it as a variable.

You can capture anything you think is relevant for the support request ticket; however, there are three pieces of end user information you must capture for an effective ticketing experience:

* Name
* Email
* Support issue

The Name and Email variables are critical requirements. Without them, the Ticketing app is not considered complete and the **Save** button won't illuminate. Though Support Issue is not a block requirement, in most cases it is essential that you capture this information. Without it, the Zendesk agent assigned to the ticket may not know what the support request is about.

> **Note**
>
> * The **Name** and **Email** variables must be titled exactly as listed above so that Zendesk recognizes them as end user profile variables and maps them correctly.
>
> * Set the Capture block **Validation** to email when capturing the end user's email address. This ensures the end user enters a valid email address by allowing the block to reject an entry that is not formed in an email address format.

#### The Fetch Chat Metadata block\[#fetch-chat-metadata-block]

The [Fetch Chat Metadata](/docs/handoffs/handoff-management/blocks/fetch-chat-metadata-block) block is necessary to capture conversation transcript and metadata, and save it as a local, global, or sensitive variable.

Attaching the end user info and the chat transcript to a [Handoff](/docs/handoffs) dialog is only possible by using the Fetch Metadata block.

#### The Zendesk Ticketing app\[#zendesk-ticketing-app]

The **Zendesk Ticketing app** is the main component of a Zendesk Support request [Handoff](/docs/handoffs), also known as a ticketing Handoff. Once triggered, a ticketing Handoff gathers the support request information from an end user. This information is then used to create a support ticket in your **Zendesk environment**. The Zendesk Ticketing app's job is to connect with the Zendesk API, which in turn takes that information and creates the ticket.

## Quick start

Complete these steps to set up a Zendesk Ticketing [Handoff](/docs/handoffs). See [Implementation & usage](#implementation--usage) for detailed instructions.

#### Configure the Zendesk Ticketing app

Authorize your Zendesk subdomain via Config > Apps > Zendesk, then configure the Zendesk Ticketing integration. See [Connect your Zendesk account](/docs/handoffs/zendesk#connect-your-zendesk-account).

#### Add Capture blocks

Capture the end user's name, email, and support issue using Capture blocks.

#### Add the Fetch Chat Metadata block

Capture the conversation transcript and metadata to attach to the ticket.

#### Add the Zendesk Ticketing app block

Configure the block with mandatory and optional inputs, then save.

## Implementation & usage

Configure the Zendesk Ticketing app and set up the [Handoff](/docs/handoffs) block by completing the following steps.

### Step 1: Configure the Zendesk Ticketing app\[#configure-the-zendesk-ticketing-app]

Connect Ada with your Zendesk Support account to use the Zendesk Ticketing app.

**To connect your Zendesk account:**

Follow the steps in [Connect your Zendesk account](/docs/handoffs/zendesk#connect-your-zendesk-account) to authorize your Zendesk subdomain.

**To configure the Zendesk Ticketing integration:**

1. On the Ada dashboard, go to **Config > AI AGENT > Handoffs**. Then, on the **Integrations** tab, beside **Zendesk Ticketing**, click **Connect**.
2. Confirm that your Zendesk subdomain is pre-populated in the configuration modal. If it is not, select it from the drop-down.
3. Click **Finish**.

### Step 2: Gather required information\[#gathering-the-information-required-to-create-a-ticket]

Gather the end user information required to create a Zendesk ticket.

The following end user information is necessary to create a Zendesk ticket:

* The end user's name
* The end user's email
* The chat transcript

You can gather the end user's **name** and **email** address by using [Capture blocks](/docs/handoffs/handoff-management/blocks/capture-block) to ask them for it directly. Remember to place the Capture blocks *before* the Zendesk Ticketing app block.

The **chat transcript**, however, must be captured using the Fetch Chat Metadata block to save it as a variable. This variable can then be attached to the ticket, typically in the **Comment** field.

#### Configure the Fetch Chat Metadata block\[#configure-fetch-chat-metadata]

Add the Fetch Chat Metadata block to capture conversation data.

**To configure the Fetch Chat Metadata block:**

1. Click the **Select Action** drop-down menu, then click **Fetch Chat Metadata**.

2. Under **Select Variables for Inputs**, add the **chatter\_token** metavariable to the **Chatter Token** field.

3. (Optional) Under **Save Response as Variables**, click the **Select Optional Variable** drop-down menu, and select the options you'd like to capture in variables.

   > **Note**
   >
   > Unlike the original Zendesk Ticketing block, this new block does not automatically capture the chat transcript or end user info (i.e., the metadata that is immediately recorded from an end user's browser/device). You must select the optional variables in this step in order to pass them to the Zendesk ticket.

4. Assign variables to the options you selected in step 3.

   > **Note**
   >
   > It is best practice to give variables the same names as the field titles. Use **chat\_transcript** and **chatter\_info**, respectively.

5. Under **Fallback Answer**, click **Edit response** to update the Error Fallback dialog to serve your end users in case of a connection error with the Zendesk API.

6. Click **Save**.

### Step 3: Use the Zendesk Ticketing app block\[#use-the-zendesk-ticketing-app]

Add the Zendesk Ticketing app block to your [Handoff](/docs/handoffs) to create support tickets.

**To add and configure the Zendesk Ticketing app block:**

1. On the **Ada Dashboard**, drag and drop the **Zendesk Ticketing App** block into your Handoff Answer.

2. Click the **Select Action** drop-down menu, then click **Create Ticket**.

   The **Select Variables for Inputs** section appears.

3. Complete the **mandatory input fields**, and any **optional input fields** as needed. Use the following tables to understand the requirements for each field.

   > **Note**
   >
   > You may see more inputs in your Optional Inputs drop-down menu than
   > the three constant options listed in the table below. The menu
   > populates with additional input options dynamically, based on what
   > is available in your Zendesk Support environment.

   <table>
     <thead>
       <tr>
         <th>
           Mandatory Input
         </th>

         <th>
           Description
         </th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>
           **Comment**
         </td>

         <td>
           Add the chat transcript variable from the Fetch Chat
           Metadata block. You can also add plaintext notes.

           > **Note**
           >
           > You can use line breaks in your comment for tidier formatting. To do
           > so, add `\n` wherever you want the line break to  occur.
         </td>
       </tr>

       <tr>
         <td>
           **Chatter's Name**
         </td>

         <td>
           Add the *Name* variable. This could be a variable captured
           with the Capture block, or a metavariable passed from the end user's
           account.
         </td>
       </tr>

       <tr>
         <td>
           **Chatter's Email**
         </td>

         <td>
           Add the *email* variable, captured either using a Capture
           block, or passed from your database as a metavariable.
         </td>
       </tr>
     </tbody>
   </table>

   <table>
     <thead>
       <tr>
         <th>
           Optional Input
         </th>

         <th>
           Description
         </th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>
           **Attach Comment To**
         </td>

         <td>
           Add one of the following to indicate where to attach the
           comment:

           * **internal note**
           * **public reply**

           > **Note**
           >
           > By default, comments are attached to internal notes.
         </td>
       </tr>

       <tr>
         <td>
           **File Data Token**
         </td>

         <td>
           Used to attach file upload data. Add the **File Data Token
           variable** generated by the File Upload App.
         </td>
       </tr>

       <tr>
         <td>
           **Tags**
         </td>

         <td>
           Use this field to add **Tags** to your tickets.

           * You can type in plain text, or use variables.
           * Separate each tag with a comma.
           * Use underscores instead of spaces in tags (e.g., `accounts,forgot_password,sign_in_issues`)
           * Avoid special characters in tags. For more information on how
             special characters work in tags, see [Working with ticket tags](https://support.zendesk.com/hc/en-us/articles/4408835059482-Working-with-ticket-tags) at Zendesk's documentation.
         </td>
       </tr>

       <tr>
         <td>
           **Email CCs**
         </td>

         <td>
           Use this field to pass CC'd recipients from an email conversation directly into a Zendesk ticket at Handoff, without requiring a custom field in Zendesk.

           When configured with the `email_latest_cc_list` variable, all CC'd participants are automatically included on the ticket, ensuring they receive replies from human agents after Handoff.

           > **Note**
           >
           > This field is only relevant when using the Zendesk Ticketing block for Email channel Handoffs involving [multiple participant conversations](/docs/channels/email/email-configuration/multiple-participant-conversations).
         </td>
       </tr>

       <tr>
         <td>
           **Custom Fields**
         </td>

         <td>
           When you create custom fields in your tickets, Zendesk
           automatically populates the names into your block. Then, you can
           associate those field names with the tag values you want to populate
           them with. For more information, see [Adding custom fields to your tickets and support request form](https://support.zendesk.com/hc/en-us/articles/4408883152794-Adding-custom-fields-to-your-tickets-and-support-request-form) at Zendesk's documentation.

           * If you have conditional fields in your ticket, ensure that each
             field has a tag in it. If a conditional field doesn't have a tag
             associated with it, the Handoff won't work. For more information, see [Creating conditional ticket fields](https://support.zendesk.com/hc/en-us/articles/4408834799770-Creating-conditional-ticket-fields) at Zendesk's documentation.

             Similarly, ensure that every field that's marked as Required in
             Zendesk has a tag associated with it. Otherwise, the Handoff won't
             work.
           * When passing tag values into custom fields, make sure you use the
             same tag names that you have configured in those fields. A common
             mistake is using the display label (e.g., `Forgot password`)
             instead of the tag value (e.g. `forgot_password`), which
             prevents the tag from properly appearing on the ticket.
         </td>
       </tr>
     </tbody>
   </table>

   ![](/_fern-img/b9330645e1a95ef38b5db590ea0a92ac51133196bb8bbbcddc8271816a6dda4a.webp)

4. Under **Save Response as Variables**, click the **Select Optional
   Variables** drop-down menu, then select **Ticket ID**.

5. Click **Choose a Variable**, and select an existing variable, or
   create a new variable, to capture the Zendesk ticket's **Ticket
   ID**.

6. Under **Fallback Answer**, click the **Choose an Answer** drop-down
   menu, then select a variable to display if an error occurs during
   the block’s operation.

7. Beside **Count as Handoff**, enable the toggle to include these Handoffs in your AI Agent's reporting.

8. Click **Save**.

You're done! The Zendesk Ticketing App block is now configured for
creating support tickets.

---

Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).