# Zendesk

Configure Zendesk ticketing integration with Risotto

## Overview

The Zendesk integration provides two-way ticket synchronization between Risotto and Zendesk Support. When a request comes through Risotto, a matching ticket appears in Zendesk. Replies and status changes in Zendesk sync back to the Risotto ticket and its Slack thread.

> **Note:** Zendesk uses **two-way sync** through a webhook that Risotto registers in your
> Zendesk account. You set up the sync for each department. Zendesk's page in
> **Settings → Integrations** has no connection of its own: it lists each
> Zendesk account that your departments use, with a link to each department's
> **Ticket Sync** settings.

## How It Works

You configure Zendesk in one place: **Settings → \<department> → Ticket Sync**. Each department has its own Zendesk credentials and its own webhook. Several departments can use the same Zendesk account.

When a ticket is created in Risotto for a configured department, Risotto:

1. Creates a matching ticket in Zendesk, with the Risotto ticket title as the subject and the ticket description as the first comment
2. Adds an **Open in Zendesk** link to the **Links** section of the Risotto ticket's detail view
3. Sends public Risotto comments to the Zendesk ticket

Risotto syncs only the tickets that it creates in Zendesk. A ticket that someone creates directly in Zendesk does not create a Risotto ticket.

## Prerequisites

> **Warning:** You need a Zendesk **Admin** account, or a custom role with the **Manage
> webhooks** permission, to generate the API token. Risotto uses the token to
> register the webhook.

### 1. Enable Token Access and Generate an API Token

1. **Open API settings**

   In Zendesk, go to **Admin Center → Apps and integrations → APIs → Zendesk API**.

2. **Enable token access**

   Turn on **Token Access** if it is off.

3. **Add an API token**

   Click **Add API token**. Give it a label, for example `Risotto`. Copy the token.

   > **Warning:** Zendesk shows the token once. If you lose it, generate a new one.

### 2. Find your Zendesk subdomain

Your subdomain is the part before `.zendesk.com`. For `mycompany.zendesk.com`, the subdomain is `mycompany`.

> **Tip:** If you paste the full Zendesk URL, Risotto extracts the subdomain for you.

## Configuration

In the **Configure Zendesk for \<department>** dialog, you enter:

| Field                      | Description                                                                              | Example               |
| -------------------------- | ---------------------------------------------------------------------------------------- | --------------------- |
| **API Token**              | The token that you generated in Zendesk                                                  | `aBc123...`           |
| **Zendesk subdomain**      | Your Zendesk subdomain, or the full URL                                                  | `mycompany`           |
| **Email Address**          | The email address of the Zendesk user who generated the API token                        | `admin@mycompany.com` |
| **Strip agent signatures** | Removes agent signatures from Zendesk comments before Risotto posts them. Off by default | Off                   |

## Setup Process

### Step 1: Add Zendesk to a department

1. **Open the department**

   In your Risotto dashboard, go to **Settings**. Under **Departments**, click a department, then click **Ticket Sync**.

2. **Add Zendesk ticket sync**

   Click **Add ticket sync** and select **Zendesk**.

   *Product example: The Add Ticket Sync for People dialog, listing the ticketing systems a department can sync with, with Zendesk highlighted.*

3. **Enter your connection details**

   In the **Configure Zendesk for \<department>** dialog, enter the **API Token**, **Zendesk subdomain**, and **Email Address**. Turn on **Strip agent signatures** if you want it.

   *Product example: The Configure Zendesk for People dialog, with an API token, the northwind subdomain, the token owner's email, Strip agent signatures off, and Save.*

4. **Save**

   Click **Save**. Risotto checks the credentials against Zendesk and registers the webhook.

   > **Done:** The **Zendesk** card on the **Ticket Sync** page shows **Connected**.

5. **Check the sync switch**

   Make sure **External ticket sync enabled** is on. It is on by default.

If Zendesk rejects the credentials, Risotto shows the error "Invalid Zendesk authentication data" and does not save the settings. If Risotto saves the settings but cannot register the webhook, your organization admins get the notification "Error registering Zendesk webhook."

### Step 2: Choose what syncs

Use these switches on the **Ticket Sync** page:

- **Only sync escalated tickets**: Risotto creates the Zendesk ticket only when the ticket escalates. Off by default.
- **Share ticket URL with requestor**: Risotto shares the Zendesk ticket URL with the requestor when the ticket escalates. Off by default.
- **Show external ticket ID**: Risotto shows the Zendesk ticket ID in the request channel. On by default.

*Product example: People's Ticket Sync page: the four sync switches with Only sync escalated tickets on, and the connected Zendesk card.*

### Step 3: Test the integration

1. **Create a test ticket**

   Create a ticket through Risotto in the configured department.

2. **Check Zendesk**

   Open Zendesk and confirm that the ticket appears.

3. **Reply in Zendesk**

   Add a public reply to the Zendesk ticket. Confirm that it appears on the
   Risotto ticket and in the requestor's Slack thread.

## What syncs

| Event                             | Direction         | What happens                                                                                                                                                          |
| --------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New Risotto ticket                | Risotto → Zendesk | Risotto creates a Zendesk ticket with priority **Normal**.                                                                                                            |
| Public comment                    | Both              | The comment appears on the other side. The requestor's Slack thread also gets the Zendesk reply.                                                                      |
| Internal note                     | Zendesk → Risotto | Risotto stores it as an internal comment and posts it in the agent channel thread. The requestor does not see it. Risotto does not send internal comments to Zendesk. |
| Risotto ticket resolved or closed | Risotto → Zendesk | Risotto sets the Zendesk ticket to **Solved**.                                                                                                                        |
| Zendesk ticket solved             | Zendesk → Risotto | Risotto sets the ticket to **Resolved**.                                                                                                                              |
| Zendesk ticket closed             | Zendesk → Risotto | Risotto sets the ticket to **Closed**.                                                                                                                                |
| Any other Zendesk status          | Zendesk → Risotto | Risotto sets the ticket to **Open**.                                                                                                                                  |
| Zendesk ticket deleted            | Zendesk → Risotto | Risotto sets the ticket to **Closed**.                                                                                                                                |

Risotto does not send fields such as the Zendesk group or assignee. It does not sync comment redactions.

Zendesk does not accept comments on a closed ticket, and a closed ticket cannot be reopened. When a reply from Risotto reaches a Zendesk ticket that Zendesk has closed, Risotto creates a Zendesk follow-up ticket of the closed ticket with that reply. From then on, the Risotto ticket links to the follow-up, and later comments and status changes sync with it.

## Change or remove the connection

On the **Ticket Sync** page, open the **Connected** menu on the **Zendesk** card.

- Click **Configure...** to change the credentials or **Strip agent signatures**. When you save, Risotto replaces the webhook.
- Click **Disconnect...** to stop the sync. Risotto deletes the webhook and clears the department's Zendesk settings.

## Troubleshooting

### Risotto shows Invalid Zendesk authentication data

- Confirm **Email Address** is the address of the Zendesk user who generated
  the token - Confirm **Token Access** is on under **Admin Center → Apps and
  integrations → APIs → Zendesk API** - Confirm the token was not revoked

### Risotto shows Error registering Zendesk webhook

The token owner is not an Admin and the role lacks **Manage webhooks**.
Generate the token from an Admin account, then click **Configure...** and
**Save** to register the webhook again.

### Tickets do not appear in Zendesk

- Confirm **External ticket sync enabled** is on for the department - If
  **Only sync escalated tickets** is on, Risotto creates the Zendesk ticket only
  after escalation

### Replies or status changes in Zendesk do not reach Risotto

- Confirm the Zendesk card shows **Connected** - Confirm the ticket was
  created by Risotto. Risotto ignores Zendesk tickets that it did not create. -
  Click **Configure...** and **Save** to register the webhook again, for example
  after someone deleted it in Zendesk

## Best Practices

1. **Use a dedicated account**: Generate the API token from an account that belongs to no person, so the sync survives staff changes
2. **Update the token in Risotto when you rotate it**: Risotto uses the stored token for every Zendesk request
3. **Test one department first**: Test with one department before you add the others

## Related Integrations

- [Ticketing Integrations Overview](https://www.tryrisotto.com/docs/integrations/ticketing/overview)
- [Zendesk Guide (Knowledge)](https://www.tryrisotto.com/docs/integrations/knowledge/zendesk-guide): index your Zendesk Guide help center articles for AI search
- [Jira Integration](https://www.tryrisotto.com/docs/integrations/ticketing/jira): two-way sync with Jira and Jira Service Management

Source: https://www.tryrisotto.com/docs/integrations/ticketing/zendesk
