Common Issues

Connection issues

Invalid API token error on connection

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.

Wrong subdomain format causing authentication failure

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.

Missing data

Chats or Agent timelines returning no data

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.

CSAT rating field is empty for all chats

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.

Some agents missing from the Agents export

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.

Permission errors

403 Forbidden when pulling certain entities

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.

Bans entity returns empty results

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.

Data discrepancies

Chat counts in Coupler.io don't match the Zendesk Chat dashboard

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.

Duration values seem much larger than expected

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.

Rate limits

Data flow fails mid-run with a rate limit error

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.