> ## Documentation Index
> Fetch the complete documentation index at: https://woku.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Zendesk Connector

> Connect your Zendesk account with woku using an API token and send tickets to your support team when feedback warrants it

The **woku Zendesk connector** links your Zendesk account with your
company in woku using an **API token**. Its purpose is to feed the
**customer support tickets** of the Support module: when the engine
detects negative feedback that warrants follow-up, woku creates a ticket
directly in your Zendesk, with the context of the customer and of the
response that originated it.

<Note>
  The connection is created only once and stays available for all Zendesk
  ticket destinations of your company. Destinations do not store their own
  credentials: they always reference the connection.
</Note>

## Before you start: get the API token in Zendesk

<Steps>
  <Step title="Open the API settings">
    In Zendesk, go to the **Admin Center** and navigate to **Apps and
    integrations → API**.
  </Step>

  <Step title="Enable token access">
    Turn on the **Token access** option. If this option is disabled in
    your account, woku will not be able to validate the credential and
    the connection will fail.
  </Step>

  <Step title="Create an API token">
    Generate a new API token and copy it. Zendesk shows it only once, so
    keep it until you finish the connection in woku.
  </Step>
</Steps>

<Tip>
  Use the email of a **real agent or administrator** of your Zendesk. The
  tickets woku creates are attributed to that user, so it is best that it
  be an active account of the support team.
</Tip>

## Create the connection in woku

In **Company → Integrations**, locate the **Zendesk** card and fill in
three fields:

| Field       | Description                                                                                                             |
| ----------- | ----------------------------------------------------------------------------------------------------------------------- |
| Subdomain   | The subdomain of your account. It accepts `acme`, `acme.zendesk.com` or the full URL; woku normalizes it automatically. |
| Agent email | The email of the agent or administrator who owns the token.                                                             |
| API token   | The token generated in the Admin Center, at least 8 characters long.                                                    |

Before saving, woku **validates the credential live** against the
Zendesk API (it queries your own user at `/api/v2/users/me.json` with
basic authentication of email and token). If the token is invalid, or
your account has token access disabled, creation fails and woku shows
you the reason.

<Note>
  A company can have **several Zendesk connections, one per subdomain**
  (duplicates are rejected). This is useful if you operate separate
  instances by country or by business unit.
</Note>

## Security and connection lifecycle

* The token is stored **encrypted** and is **write-only**: the interface
  never shows it again, only a masked hint.
* To **rotate the token**, edit the connection and enter the new value.
  woku verifies it live against Zendesk before persisting it; if it is
  not valid, the connection keeps the previous token.
* The **Test** button re-verifies the connection at any time and records
  its health. If Zendesk responds with an authentication error, the
  connection is marked as **requires re-authentication**.
* Each connection shows its status: **connected**, **requires
  re-authentication** or **error**. You can also **enable or disable it**
  without losing the configuration, or **delete it** entirely.

## What woku does with the connection

The connection feeds the **customer support ticket destinations** of the
Support module. A Zendesk destination references the connection and,
optionally, a **Group ID**: the Zendesk agent group that will receive
the tickets from that destination.

When the engine escalates negative feedback, woku creates the ticket in
your Zendesk (`/api/v2/tickets.json`) with:

* **Subject** and **HTML description** with the summary of the case.
* **Requester**: the name and email of the affected customer, so that
  the ticket is associated with the correct person.
* **Priority** mapped according to the severity of the case: `urgent`,
  `high`, `normal` or `low`.
* **Tags**: `woku`, `voc`, the source tool (woku, NPS, CSAT or CES) and
  the customer's churn risk level.
* **Group**: the destination's Group ID, if you configured it.

The link to the created ticket is stored in woku. From the ticket detail
you can open it in Zendesk with **View in customer support**.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="What permissions does the token need?">
    The token inherits the permissions of the agent whose email you
    configured. To create tickets a standard agent is enough; use an
    administrator if your account restricts ticket creation via API.
  </Accordion>

  <Accordion title="What happens if I rotate or revoke the token in Zendesk?">
    The connection will stop authenticating and, on the next
    verification, will be marked as **requires re-authentication**. Edit
    the connection and enter the new token; woku validates it live before
    saving it.
  </Accordion>

  <Accordion title="Can I connect more than one Zendesk account?">
    Yes. You can create several connections, as long as each one points
    to a **different subdomain**. Then each ticket destination chooses
    which connection to use.
  </Accordion>

  <Accordion title="What happens to the tickets if I delete the connection?">
    Tickets that are already created **remain in your Zendesk**: woku only
    deletes the connection and its credentials. The destinations that
    depended on it can no longer send until you point them to another
    connection.
  </Accordion>
</AccordionGroup>

## Next step

<Card title="Customer support tickets" href="/docs/en/guias/tickets-sac" horizontal>
  Learn about the escalation engine: how the feedback that warrants a
  ticket is detected, how it is routed to each destination and how
  follow-up is done from woku.
</Card>