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

# Zendesk Read Ticket

> Native Zendesk ticket-read tool exposed through the Agents Platform.

This document covers `zendesk_read_ticket`, the native Zendesk ticket-read tool exposed through the Agents Platform.

## Authentication & enablement

Zendesk tools use a per-workspace **Zendesk connection** created in **Settings → Integrations → Zendesk**. Pick one of two auth methods when connecting:

* **API token** — enter your **Zendesk URL** (e.g. `https://acme.zendesk.com`), the **agent email**, and an **API token** (Admin Center → Apps and integrations → APIs → Zendesk API → add token). Calls authenticate with HTTP Basic `{email}/token:{api_token}`.
* **OAuth** — create an OAuth client in your **own** Zendesk (Admin Center → Apps and integrations → APIs → OAuth clients; client kind **Confidential**, redirect URL = the platform's OAuth callback), then when connecting enter your **Zendesk URL** plus that client's **client ID** and **client secret** and click through Zendesk's authorization page (use this if your account has API tokens disabled). Calls authenticate with `Bearer <access_token>`, refreshed automatically. The OAuth app is per-workspace — there is no shared server-side Zendesk app — so it works for any Zendesk subdomain without a Zendesk "global" client.

Either way, the credentials are injected into the tool at run time from the connected integration and are never visible to the model.

Both Zendesk tools are **off by default** — add them to an agent explicitly.

## `zendesk_read_ticket`

Reads a Zendesk ticket by its numeric id. It does not modify the ticket, but it is not free of side effects: it copies the ticket's intake attachments into platform file storage (see [Output](#output)) so they can be previewed and processed downstream.

### Inputs

Required:

* `ticket_id`: the numeric Zendesk ticket id (e.g. `"12345"`).

`url`, `email`, and `api_token` are injected from the connected integration — the agent does not supply them.

### Output

```json theme={null}
{
  "tool_name": "zendesk_read_ticket",
  "ticket_id": "12345",
  "subject": "Refund request",
  "status": "open",
  "description": "First comment body…",
  "attachments": [
    { "file_name": "receipt.pdf", "content_url": "https://…", "content_type": "application/pdf", "size": 10240, "file_id": "3f2a…", "file_url": "${VAR_1}" }
  ],
  "custom_fields": { "360000012345": "Reviewed" },
  "tags": ["billing", "priority"],
  "assignee_id": 908070,
  "is_assigned": true,
  "ticket_url": "https://acme.zendesk.com/agent/tickets/12345"
}
```

* `description` is the ticket's first-comment body.
* `attachments` are the **first comment's** attachments (the ticket's intake files); empty if none — fall back to `description`. The rest of the conversation's attachments are out of scope here — a future `zendesk_list_comments` tool would cover those.
* Each attachment (≤ 50 MB, and at most the first 20 per read) is copied into platform file storage at read time. Two references are returned: `file_id` (so the UI can preview it in the app — our own storage is same-origin/CORS-open, unlike the raw `content_url`) and `file_url` (a value the agent can pass straight to `structured_data_extraction` or other file tools to read the contents — a `${VAR_N}` ref that resolves to the stored file's S3 URL, or the raw S3 URL for CodeAct tasks). Best-effort: if the copy fails — or the attachment is over 50 MB or beyond the 20-per-read cap — both refs are omitted and only `content_url` is returned. Storing is skipped entirely when file storage isn't wired (e.g. schema-only mode).
* `custom_fields` maps field id (as a string) → value.
* `is_assigned` is a convenience for deciding whether to write back.
* `ticket_url` is the ticket's Zendesk web URL (omitted if the connection URL can't be normalized).

### Limits & errors

* Fetches the ticket plus its first comment (for attachments); the comment fetch is best-effort, so a failure there still returns the ticket (without attachments).
* `HTTP 404` → check the `ticket_id`.
* `HTTP 401/403` → the workspace's Zendesk credentials are invalid; reconnect the integration.
* "Zendesk is not connected…" → no active Zendesk integration exists for the workspace.

## Agent Instruction Guidance

Call this before `zendesk_write_ticket` whenever you need the ticket's current state — for example to implement a "skip if already assigned" rule: read the ticket, check `is_assigned`, and only write when it is `false`. The write tool intentionally does not enforce that guard, so the decision lives here in the agent.