> 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/project-management/slack/best-practices.md).

# 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 User tokens, not Bot tokens</strong></td><td>Only User OAuth tokens support the search:read scope needed for message exports. Generate your token from a user account that's a member of all relevant channels.</td></tr><tr><td><strong>Always scope your search query</strong></td><td>Use the in:#channel modifier to limit message exports to specific channels. Broad queries across the whole workspace return noisy results and hit Slack's API limits faster.</td></tr><tr><td><strong>Combine entities with Join or Append</strong></td><td>Use the Join transformation to enrich message exports with user profile data — match the user ID field from Messages to the ID field in Users to get real names and roles alongside each message.</td></tr><tr><td><strong>Send conversation data to AI destinations</strong></td><td>Route exported messages to Claude, ChatGPT, or Gemini to automatically summarize channel discussions, tag topics, or flag action items — no manual reading required.</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>Use date-range queries for incremental exports</strong></td><td>Slack's search API doesn't support true incremental syncs. Instead, structure your search query with after: and before: date modifiers to pull only recent messages and avoid re-exporting the full history every time.</td></tr><tr><td><strong>Schedule Users and Channels less frequently</strong></td><td>User and channel lists change slowly. A daily or weekly refresh is usually enough. Reserve more frequent schedules for active message channels where new data arrives constantly.</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>Break large history exports into chunks</strong></td><td>If you need several months of messages, create separate data flows with different date ranges rather than one broad query. This avoids hitting Slack's search result caps and keeps individual runs fast.</td></tr><tr><td><strong>Append multi-channel data in one data flow</strong></td><td>Instead of creating separate data flows per channel, use the Append transformation to pull messages from multiple channels into a single output. Add a channel identifier to each source so you can filter later.</td></tr></tbody></table>

## Common pitfalls

{% hint style="danger" %}
Do not use a Bot token expecting to export messages — `search:read` is not available to bots and the Messages entity will return no data.
{% endhint %}

{% columns %}
{% column %}
**Do**

* Use a User token scoped to the channels you need
* Test your search query in Slack before configuring the data flow
* Filter out bot users (`is_bot = true`) when analyzing headcount from the Users entity
* Use the Join transformation to attach user names and roles to message exports
  {% endcolumn %}

{% column %}
**Don't**

* Use an overly broad query (no channel or date filter) — results will be unreliable and slow
* Expect file attachments or images to be exported — only metadata is available
* Assume thread replies will appear in channel-level search results
* Use one data flow to pull months of messages without date-range scoping
  {% endcolumn %}
  {% endcolumns %}


---

# 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/project-management/slack/best-practices.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.