Best Practices

Recommended setup

Use an Admin API token

Generate your API token from an Admin account. Agent-level tokens silently block access to Roles, Bans, Routing settings, and Account data — you won't always get an obvious error.

Set a realistic start date for Chats

Avoid pulling your entire chat history in one go. Start with the last 30–90 days, validate the data, then expand the range. Very long date ranges on busy accounts can hit API rate limits mid-run.

Join Chats with Agents for meaningful reports

The Chats entity stores agent_ids, not names. Add the Agents entity as a second source and use Coupler.io's Join transformation to enrich chat records with agent names, roles, and departments.

Data refresh and scheduling

Schedule Chats and Agent timelines separately

These two entities are the only date-scoped ones. Run them on a daily or hourly schedule depending on your reporting needs. Configuration entities like Roles and Shortcuts change rarely — a weekly refresh is sufficient.

Use Append for historical chat datasets

If you're building a growing history of chats, use Coupler.io's Append mode so each scheduled run adds new records rather than overwriting the full dataset. This keeps your destination lean and your run times fast.

Performance optimization

Separate high-volume from low-volume entities

Chats can return thousands of records per run on active accounts. Keep it in its own data flow rather than mixing it with small config entities like Shortcuts or Skills — this makes troubleshooting faster and runs more predictable.

Aggregate before sending to spreadsheets

If your destination is Google Sheets or Excel, use Coupler.io's Aggregate transformation to pre-summarize metrics (e.g., daily chat count, average response time by department) before loading. Raw chat exports can quickly exceed spreadsheet row limits.

Common pitfalls

Don't rely on the rating field without checking CSAT settings first. If CSAT surveys aren't enabled in Zendesk Chat, every chat will show an empty rating — which looks like 0% satisfaction but actually means no data was collected. Validate your CSAT configuration before building satisfaction reports.

Do

• Filter chats by type field to separate live chats from offline messages

• Join Agent timelines with Agents to get readable names alongside status data

• Use the Aggregate transformation to summarize metrics before loading to spreadsheets

• Test with a short date range before expanding to full history

Don't

• Use an Agent-role API token for full data access

• Pull full chat history in one run on a large account

• Mix high-volume entities (Chats) with config entities in the same data flow

• Treat duration as minutes — it's always in seconds