Skip to main content

conversations.history method

Welcome to the new home of Slack developer docs!

We're still building and not all features are available quite yet. Enjoy this peek into the future!

Not ready for the future? Return to the past at api.slack.com.

Usage info​

This method returns a portion of message events from the specified conversation. Call the method with no oldest or latest arguments to read the entire history for a conversation.

Each type of token can be used to access a set of conversations given the proper scopes.

Token typeRequired scopesAccessible conversations
App-level access tokenRelevant *:history scopeAny conversation the relevant app is a member of.
Bot tokenRelevant *:history scopeAny conversation the relevant bot is a member of.
User tokenRelevant *:history scopeAny private conversation the user is a member of, and all public conversations.
Legacy bot user tokensDirect message and multi-party direct message conversations.

Response​

Pagination​

This method uses cursor-based pagination to make it easier to incrementally collect information. To begin pagination, specify a limit value under 1000. We recommend no more than 200 results at a time.

Responses will include a top-level response_metadata attribute containing a next_cursor value. By using this value as a cursor parameter in a subsequent request, along with limit, you may navigate through the collection page by virtual page.

See pagination for more information.

Pagination by time​

This form of pagination can be used in conjunction with cursors.

The messages array contains up to 100 messages between the oldest and latest timestamps. The most recent messages in the time range are returned first.

If there were more than 100 messages between oldest and latest, then has_more will be true in the response. In an additional call, set the ts value of the final message as latest to get the next page of messages.

If a message has the same timestamp as oldest or latest it will not be included in the list. This functionality allows you to use the timestamps of specific messages as boundaries for the results. You can, however, have both timestamps be included in the time range by setting inclusive to true. The inclusive parameter is ignored when oldest or latest is not specified.

Retrieving a single message​

conversations.history can also be used to find a single message from the archive.

You'll need a message's ts value, uniquely identifying it within a conversation. You'll also need that conversation's ID.

If you know the ts of a specific message:

  1. Set oldest to the ts
  2. Set inclusive to true
  3. Set limit to 1

If you know the ts of the message that is before or after of the specific message you're looking for; set inclusive to false and use the oldest or latest value respectively.

Provide another message's ts value as the latest parameter. Set limit to 1. If it exists, you'll receive the queried message in return.

Finally, use inclusive=true because otherwise we'll never retrieve the message we're actually after, just the ones that come after it.

GET /api/conversations.history?channel=C123ABC456&latest=1476909142.000007&inclusive=true&limit=1
Authorization: Bearer TOKEN_WITH_CHANNELS_HISTORY_SCOPE

To retrieve a message from a thread, check out conversation.replies.

You can easily generate a permalink URL for any specific message using chat.getPermalink.

Retrieving message history from a direct message​

conversations.history can also be used to export messages from a direct message.

In addition to a bot token, you'll need to input the direct message ID (similar to a conversation ID and beginning with D) in order to retrieve the message history. You can find the direct message ID by using the conversations.list method.

Message types​

Messages of type "message" are user-entered text messages sent to the channel, while other types are events that happened within the channel. All messages have both a type and a sortable ts, but the other fields depend on the type. For a list of all possible events, see the channel messages documentation.

Messages that have been reacted to by team members will have a reactions array delightfully included. If you need a full list of reactions for a message, use the reactions.get method.

If a message has been starred by the calling user, the is_starred property will be present and true. This property is only added for starred items, so is not present in the majority of messages.

The is_limited boolean property is only included for free teams that have reached the free message limit. If true, there are messages before the current result set, but they are beyond the message limit.