> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/crm/zendesk-chat/common-issues.md).

# Common Issues

## Connection issues

<details>

<summary>Invalid API token error on connection</summary>

Double-check that you copied the full API token without any trailing spaces. In Zendesk Chat, go to **Settings → Account → API** and regenerate the token if needed. Also confirm you're using the correct subdomain — it should match exactly what appears in your Zendesk Chat URL.

</details>

<details>

<summary>Wrong subdomain format causing authentication failure</summary>

Your subdomain should be just the prefix before `.zendesk.com` — for example, if your URL is `acme.zendesk.com`, enter `acme`. Do not include `https://` or `.zendesk.com` in the subdomain field.

</details>

## Missing data

<details>

<summary>Chats or Agent timelines returning no data</summary>

Check that you've set a start date using the date picker. The **Chats** and **Agent timelines** entities require a start date — without one, the export may return empty results. Set the start date to a period when you know chat activity occurred.

</details>

<details>

<summary>CSAT rating field is empty for all chats</summary>

The `rating` field only populates when CSAT surveys are enabled in your Zendesk Chat account and when visitors actually submit a rating. If CSAT is disabled or visitors didn't respond, this field will be blank. Check your CSAT settings under **Settings → Chat → Satisfaction**.

</details>

<details>

<summary>Some agents missing from the Agents export</summary>

Deactivated or deleted agents may not appear in the Agents entity. If you need historical data for former agents, look for their IDs in the Chats entity — agent\_ids are preserved even after an agent is removed.

</details>

## Permission errors

<details>

<summary>403 Forbidden when pulling certain entities</summary>

Some entities — particularly Roles, Routing settings, and Account — require Admin-level access. If your API token belongs to an Agent-role user, you'll get a 403 on restricted endpoints. Generate the API token from an Admin account to resolve this.

</details>

<details>

<summary>Bans entity returns empty results</summary>

Accessing the Bans entity requires Admin permissions. If the entity returns empty results but you know bans exist, check that the token owner has Admin rights in Zendesk Chat.

</details>

## Data discrepancies

<details>

<summary>Chat counts in Coupler.io don't match the Zendesk Chat dashboard</summary>

Zendesk Chat dashboards often include offline messages alongside live chats. In the Chats entity, filter by the `type` field — `chat` for live conversations and `offline_msg` for messages left when no agents were available. Make sure both types are accounted for in your comparison.

</details>

<details>

<summary>Duration values seem much larger than expected</summary>

The `duration` field is measured in seconds, not minutes. Divide by 60 in your spreadsheet or BI tool to convert to minutes. For example, a duration of 360 = 6 minutes.

</details>

## Rate limits

<details>

<summary>Data flow fails mid-run with a rate limit error</summary>

Zendesk Chat's API enforces rate limits that vary by plan. If you're exporting a large date range of Chats, try splitting the export into shorter time windows using the start date picker. Running large historical exports during off-peak hours can also reduce the chance of hitting limits.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.coupler.io/sources/category/crm/zendesk-chat/common-issues.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.