# Best Practices

## Recommended setup

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Use an Admin API token</strong></td><td>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.</td></tr><tr><td><strong>Set a realistic start date for Chats</strong></td><td>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.</td></tr><tr><td><strong>Join Chats with Agents for meaningful reports</strong></td><td>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.</td></tr></tbody></table>

## Data refresh and scheduling

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Schedule Chats and Agent timelines separately</strong></td><td>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.</td></tr><tr><td><strong>Use Append for historical chat datasets</strong></td><td>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.</td></tr></tbody></table>

## Performance optimization

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Separate high-volume from low-volume entities</strong></td><td>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.</td></tr><tr><td><strong>Aggregate before sending to spreadsheets</strong></td><td>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.</td></tr></tbody></table>

## Common pitfalls

{% hint style="danger" %}
**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.
{% endhint %}

{% columns %}
{% column %}
**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
  {% endcolumn %}

{% column %}
**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
  {% endcolumn %}
  {% endcolumns %}