> 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.md).

# Zendesk Chat

Connect Zendesk Chat to Coupler.io to pull live chat conversations, agent activity, and routing data into Google Sheets or data warehouses.

Zendesk Chat is a live chat platform that lets support and sales teams talk to customers in real time on websites and apps. It tracks conversations, agent performance, routing rules, and visitor behavior all in one place. Connecting it to Coupler.io lets you pull that data into your reporting tools automatically.

## Why connect Zendesk Chat to Coupler.io?

* **Centralize support analytics** — combine chat data with CRM, helpdesk, or marketing data in one destination
* **Track agent performance** — export agent timelines, chat volumes, and department metrics without manual exports
* **Automate reporting** — send fresh data to Google Sheets, BigQuery, Looker Studio, or AI tools like ChatGPT or Gemini on a schedule
* **Combine multiple entities** — use Append or Join transformations to merge chats with agent data or department info in a single dataset

## Prerequisites

* A Zendesk Chat account (any plan)
* Access to generate an API token in Zendesk Chat
* Agent or Admin role (Admin recommended for full data access)

## Quick start

{% hint style="success" %}
Start with the **Chats** entity — it's the most data-rich and immediately useful for support performance reporting.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Create a new data flow in Coupler.io.** Log in to your Coupler.io account, go to the Data Flows section, and click **Add data flow**. Search for and select **Zendesk Chat** as your source.
{% endstep %}

{% step %}
**Get your Zendesk Chat API token.** In Zendesk Chat, go to **Settings → Account → API**. Generate a new OAuth token or use your existing API credentials. Copy the token — you'll need it in the next step.
{% endstep %}

{% step %}
**Enter your API credentials in Coupler.io.** Paste your API token into the connection fields. You'll also need to provide your Zendesk Chat subdomain (the part before `.zendesk.com` in your URL).
{% endstep %}

{% step %}
**Select an entity.** Choose which data you want to import — for example, **Chats**, **Agents**, or **Agent timelines**. For the Chats and Agent timelines entities, use the date picker to set a start date for your data export.
{% endstep %}

{% step %}
**Choose a destination.** Select where you want your data to land — Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination like Claude, ChatGPT, or Perplexity. Configure the destination settings as prompted.
{% endstep %}

{% step %}
**Run your data flow.** Click **Run** to execute a manual sync. Once it completes successfully, your Zendesk Chat data will appear in your chosen destination.
{% endstep %}
{% endstepper %}

## Available entities

| Entity           | Description                                |
| ---------------- | ------------------------------------------ |
| Accounts         | Account-level settings and configuration   |
| Agents           | Agent profiles and status information      |
| Agent timelines  | Activity logs and status changes per agent |
| Bans             | Blocked visitors and IP addresses          |
| Chats            | Full chat conversation records             |
| Departments      | Department definitions and assignments     |
| Goals            | Performance targets for chat teams         |
| Roles            | Role and permission definitions            |
| Routing settings | Chat assignment and routing configuration  |
| Shortcuts        | Saved message templates for agents         |
| Skills           | Agent skills used for routing              |
| Triggers         | Automated chat rules and conditions        |

## Zendesk Chat data overview

Zendesk Chat exposes a wide range of operational and configuration data through Coupler.io. The most analytically valuable entities are **Chats** and **Agent timelines** — these contain the conversation records and activity logs that power support performance reporting.

## Entities at a glance

| Entity           | Best used for                                | Supports date range? |
| ---------------- | -------------------------------------------- | -------------------- |
| Chats            | Conversation analytics, response times, CSAT | Yes                  |
| Agent timelines  | Availability tracking, shift analysis        | Yes                  |
| Agents           | Team roster, capacity planning               | No                   |
| Departments      | Routing analysis, team structure             | No                   |
| Goals            | Performance benchmarking                     | No                   |
| Skills           | Routing logic review                         | No                   |
| Triggers         | Automation audit                             | No                   |
| Shortcuts        | Template usage review                        | No                   |
| Roles            | Permissions audit                            | No                   |
| Bans             | Moderation reporting                         | No                   |
| Routing settings | Configuration documentation                  | No                   |
| Accounts         | Account-level audit                          | No                   |

## Chats entity

#### Conversation identifiers

| Field          | Description                                 |
| -------------- | ------------------------------------------- |
| id             | Unique chat session ID                      |
| session\_id    | Browser session identifier                  |
| visitor\_id    | Unique visitor identifier                   |
| department\_id | Department that handled the chat            |
| agent\_ids     | List of agents involved in the conversation |

#### Conversation details

| Field          | Description                                          |
| -------------- | ---------------------------------------------------- |
| started\_by    | Whether the chat was initiated by visitor or trigger |
| type           | Chat type (chat, offline\_msg)                       |
| channel        | Channel through which the chat arrived               |
| tags           | Labels applied to the chat                           |
| message\_count | Total messages exchanged                             |
| missed         | Whether the chat was missed                          |
| rating         | Visitor satisfaction rating                          |
| comment        | Visitor's CSAT comment                               |

#### Timing fields

| Field          | Description                                |
| -------------- | ------------------------------------------ |
| timestamp      | Chat start time                            |
| end\_timestamp | Chat end time                              |
| duration       | Total chat duration in seconds             |
| wait\_time     | Time visitor waited before agent responded |
| response\_time | Agent's first response time in seconds     |

## Agent timelines entity

#### Activity fields

| Field       | Description                            |
| ----------- | -------------------------------------- |
| agent\_id   | ID of the agent                        |
| start\_time | When the status period began           |
| end\_time   | When the status period ended           |
| duration    | Length of the status period in seconds |
| status      | Agent status (online, away, invisible) |

## Agents entity

#### Agent profile fields

| Field       | Description                         |
| ----------- | ----------------------------------- |
| id          | Unique agent ID                     |
| name        | Agent display name                  |
| email       | Agent email address                 |
| role        | Assigned role                       |
| departments | Departments the agent belongs to    |
| skills      | Skills assigned to the agent        |
| enabled     | Whether the agent account is active |

## Common metric combinations

* **Chats + Agents** (Join on agent\_id) — add agent names and roles to conversation records for team-level reporting
* **Chats + Departments** (Join on department\_id) — analyze volume and CSAT by department
* **Agent timelines + Agents** (Join on agent\_id) — calculate total online hours per agent per day
* **Multiple date ranges of Chats** (Append) — combine data from different periods into a single historical dataset

## Use cases by role

{% tabs %}
{% tab title="Support managers" %}

* Track first response time and chat duration trends over time using the Chats entity
* Monitor agent availability and online hours by joining Agent timelines with Agents
* Compare CSAT ratings across departments to identify coaching opportunities
* Use Aggregate transformation in Coupler.io to summarize daily chat volumes without leaving the platform
  {% endtab %}

{% tab title="Operations teams" %}

* Audit routing rules by exporting Triggers, Skills, and Routing settings into a single spreadsheet
* Use the Departments entity to map team structures and verify correct routing assignments
* Track missed chat rates over time to identify understaffing periods
* Export Goals data to compare actual performance against targets in Looker Studio or BigQuery
  {% endtab %}

{% tab title="AI & analytics" %}

* Send Chats data to ChatGPT or Claude to summarize recurring customer issues or generate weekly support digests
* Use Gemini or Perplexity with agent timeline exports to get plain-language summaries of availability patterns
* Pipe raw chat transcripts and tags into an AI destination for theme detection and auto-labeling
  {% endtab %}
  {% endtabs %}

## Platform-specific notes

* The **start\_date** parameter only applies to the **Chats** and **Agent timelines** entities — all other entities return full records regardless of date
* Chat `duration` is measured in seconds — divide by 60 in your destination tool for minutes
* The `rating` field only populates if CSAT is enabled in your Zendesk Chat account and the visitor submitted a rating
* `agent_ids` on a chat may contain multiple values if the chat was transferred between agents
* Banned users are stored separately in the **Bans** entity and are not flagged within the Chats entity itself

## Zendesk Chat 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>

## Zendesk Chat FAQ

<details>

<summary>What is the difference between Zendesk Chat and Zendesk Support in Coupler.io?</summary>

Zendesk Chat is a standalone live chat product focused on real-time conversations, agent availability, and chat routing. Zendesk Support is a ticketing system for managing longer-running customer issues. They have separate APIs and separate Coupler.io connectors. If you use both, you can combine data from each using Coupler.io's Join or Append transformations in a single data flow.

</details>

<details>

<summary>Can I export full chat transcripts, or just metadata?</summary>

The Chats entity includes message-level data for each conversation, not just metadata. You'll get timestamps, agent and visitor messages, tags, ratings, and session details. The exact transcript content depends on your Zendesk Chat plan and data retention settings.

</details>

<details>

<summary>How do I get agent names into my chat export?</summary>

The Chats entity stores agent identifiers (agent\_ids), not names. To get human-readable names, add the Agents entity as a second source in your data flow and use Coupler.io's Join transformation to match agent\_ids to agent names, roles, and departments.

</details>

<details>

<summary>Why does my Chats entity return no rows when I run the data flow?</summary>

The most common reason is a missing or incorrect start date. The Chats entity requires a start date — use the date picker to set one. Also confirm that your API token has the correct permissions and that the account had chat activity during the selected period.

</details>

<details>

<summary>Can I pull data from multiple Zendesk Chat accounts into one destination?</summary>

Yes. Add multiple sources within the same data flow — one per account — and use Coupler.io's Append transformation to combine them. This is useful if your organization operates separate Zendesk Chat accounts for different brands or regions.

</details>

<details>

<summary>Which entities require Admin-level access?</summary>

Roles, Bans, Routing settings, and Accounts all require an Admin API token. Using an Agent-level token will result in 403 errors or empty responses for these entities. Generate your token from an Admin user account to avoid this.

</details>

<details>

<summary>Can I send Zendesk Chat data to an AI tool?</summary>

Yes. Coupler.io supports AI destinations including ChatGPT, Claude, Gemini, Perplexity, Cursor, and OpenClaw. You can send chat records or agent performance summaries directly to these tools for analysis, summarization, or generating support insights.

</details>

<details>

<summary>How far back can I pull historical chat data?</summary>

This depends on your Zendesk Chat plan's data retention policy. Coupler.io will retrieve whatever Zendesk Chat makes available through its API for your account tier. Use the date picker to set your start date, and check your Zendesk Chat plan documentation for retention limits.

</details>

{% hint style="info" %}
For field-level details on what each entity returns, see the [Data Overview](#zendesk-chat-data-overview) article. For help with empty exports, authentication errors, or mismatched numbers, check [Common Issues](#zendesk-chat-common-issues).
{% endhint %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
