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

# Zendesk ticket ingestion

> Let the AI Agent assess every new Zendesk ticket from a contact form without changing the ticket.

Zendesk notifies Typewise each time a ticket is created. Typewise then reads the
ticket over the Zendesk API and creates it in the platform the way a
[Form API](https://docs.typewise.app/guides/channels/form-api.md) submission arrives, linked to the Zendesk
ticket through `crmTicketId`. The AI Agent assesses it from there.

Typewise only tags the ticket during ingestion. Its status, assignee and group
stay as they were, so your agents still see it as **New**.

> [!NOTE]
>
> [Connect Zendesk](https://docs.typewise.app/documentation/integrations/supported/zendesk-oauth.md) first.
> Ingestion uses the same integration.

## Set up

**1. Create the webhook in Zendesk**

In Admin Center go to **Apps and integrations → Webhooks → Create webhook**.

* **Connection type:** Trigger or automation
* **Endpoint URL:** `https://platform-api.typewise.app/api/webhooks/zendesk/<workspaceId>`
  where `<workspaceId>` is the id of your Typewise workspace
* **Request method:** POST
* **Request format:** JSON
* **Authentication:** None. Requests are verified with the signing secret.

Zendesk only finishes the webhook once a trigger uses it, so create the
trigger in the next step, then come back and click **Finish setup**.

**2. Store the signing secret in Typewise**

Open the webhook's **Activity → Signing secret** (or call
`GET /api/v2/webhooks/{id}/signing_secret`) and copy the secret.

In Typewise, open the Zendesk integration and paste it into
**Webhook signing secret**. Deliveries with a missing or wrong signature are
rejected.

**3. Create the trigger**

Go to **Objects and rules → Business rules → Triggers → Add trigger**.

* **Conditions:** `Ticket > Ticket Is > Created` and
  `Ticket > Tags > Contains none of the following` with `typewise_sent`,
  `typewise_handled` and `typewise_handover`, each entered as its own tag
  (press Enter after each one), so tickets Typewise creates itself are not
  sent back. To limit the pilot to one form, add
  `Ticket > Form > Is > <your contact form>`.
* **Actions:** `Notify active webhook` only, pointing at the webhook above.

Use this JSON body. The ticket id is enough: Typewise fetches the rest.

```json theme={null}
{
  "ticket_id": "{{ticket.id}}",
  "form_id": "{{ticket.ticket_form_id}}"
}
```

> [!WARNING]
>
> Do not add status, assignee or group actions to this trigger. Any of
> them moves the ticket out of **New**.

## What lands in Typewise

| In Zendesk | In Typewise |
| :- | :- |
| Requester | End customer (email and name) |
| Subject | Ticket subject |
| Description | First customer message |
| Attachments on the first comment | Message attachments |
| Custom form fields | Ticket variables, named after the field title |
| Ticket id | `crmTicketId`, plus `Zendesk Ticket ID` and `Zendesk Ticket URL` |
| Form id | `Zendesk Form ID` |

Because `crmTicketId` is set, a later handoff or backup to Zendesk updates this
ticket instead of creating a new one.

> [!NOTE]
>
> Typewise only keeps variables that are declared as context variables in the
> workspace. Declare `Zendesk Ticket ID`, `Zendesk Ticket URL`, `Zendesk Form
>     ID` and the titles of the form fields you want to see; undeclared ones are
> dropped at ingest and listed in a backend warning.

## Tags

Typewise adds `typewise_sent` to each ticket it ingests, so your agents and
views can tell them apart. Typewise itself never changes the ticket's status;
check that none of your own triggers reacts to these tags. The `typewise_`
prefix is reserved: Typewise treats any ticket carrying such a tag as one it
already knows, so do not use the prefix for tags of your own.

What happens to the tag once the AI Agent is done, for example swapping it for
`typewise_handled` or `typewise_handover`, is set up per customer with your
Typewise contact. Tickets Typewise creates itself, for example from a chat,
carry a `typewise_` tag from the start, and Typewise skips them if the trigger
still sends them.

## Behaviour

* Typewise acknowledges a delivery within milliseconds and processes it in the
  background. A delivery Zendesk sends twice creates one ticket.
* New tickets go through the same
  [spam classification](https://docs.typewise.app/documentation/behavior/email.md#spam-classification) as
  the Form API.
* When ingestion fails for good, the ticket stays untouched in Zendesk and your
  agents handle it as usual.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.