You must enable javascript in order to use the Slack API Documentation. You can do this in your browser settings.
Go to Slack

User presence and status

Slack users can toggle whether they are marked active or away. They can also set their own custom status, informing their team not only that they are at lunch, but exactly what they are eating.

Custom status

A set custom status as it appears within a conversation

Users can declare their status by selecting a custom emoji icon and string of text to represent their "current status" — maybe they're in another office, on the good old telephone, sailing, vacationing in the sticks, or possibly eaten by a grue.

Some users want to fly the freak flag and use this space to wax poetic while others won't touch the stuff, or only in the most perfunctory way.

We encourage developers to embrace all the ways users and teams enjoy utilizing custom status. Slack is where workplay happens.

Custom status is part of a user's profile and setting status requires the users.profile:write scope. At this time, bot users do not have a user profile and are without status, current, custom, or otherwise.

Reading statuses

Determine a user's currently set custom status by consulting their profile. You'll find profiles attached to user objects returned by users.list and users.info. Both methods require the users:read OAuth scope.

More directly retrieve status for a specific user with users.profile.get with the users.profile:read scope.

A user's custom status is represented by the status_text and status_emoji profile attributes.

  • status_text - a string of no more than 100 characters; does not support markup or other formatting, like user mentions. May contain :emoji: references.
  • status_emoji - a string corresponding to an emoji installed on the team. Animated emoji will appear frozen. When clearing the attribute, a default emoji (currently 💬 / :speech_balloon:) will be selected for the user.

To be notified when status and other profile fields change, subscribe to user_change events in the Events API or use the RTM API to stream and monitor.

Writing custom statuses

Set a user's custom status by using their access token with users.profile.set and the users.profile:write scope.

You'll need to provide the profile parameter a URL-encoded JSON string containing at least the status_text attribute.

For example, to set a custom status of riding a train with an emoji set to this idyllic scene: 🚞, build a JSON payload like this:

{
    "status_text": "riding a train",
    "status_emoji": ":mountain_railway:"
}

Then encode it as the URL-encoded profile parameter and send it to Slack:

POST slack.com/api/users.profile.set
token=super_secret_token&profile=%7B%22status_text%22%3A%22riding%20a%20train%22%2C%22status_emoji%22%3A%22%3Amountain_railway%3A%22%7D

As with other profile fields, these fields may be set on their own or while updating multiple profile fields.

To unset a user's custom status, set both status_text and status_emoji to empty strings: "".

That's how to sync status with calendars, cubicles, conference calls, and bathroom stalls.


User presence

A user can have one of two possible presence values, active or away. A user is active if they have at least one client connected to Slack, and they are not marked as "away". There are two ways a user can be marked as away: automatic and manual.

Automatic Away

The Slack message servers will automatically detect activity based on messages sent from a client. If they detect no messages in 30 minutes, the user is marked as automatically away.

However, it's possible to actively use a Slack client without causing any messages to be sent; in these situations the client can indicate activity has occurred by calling the API. Every Slack API method accepts an additional set_active argument. This can be used to indicate activity has occurred while performing the requested action.

If the user's activity generates no API calls then the client can periodically call users.setActive to let the Slack servers know about that activity.

These auto-away rules do not apply to Bot Users.

Manual Away

An application can call users.setPresence to manually mark a user as away or auto. A manual status set using this method will persist between connections.

A manual away status set using this method overrides the automatic presence determined by the message server.

Setting presence back to auto indicates that the automatic status should be used instead. There's no way to force a user status to active.

Bot presence

Bot users have their own form of being present on Slack.

When marked away, bots will have a grey dot next to their name. Many users interpret this demarcation to mean your bot is not currently available.

And when they are active, bots will have a green dot there. Users have been known to consider your green dot a badge of conversational readiness.

It's either/or. away or active. Grey or green.

Please don't use presence to telegraph Morse code or teach your bot to speak the binary language of moisture vaporators. Use chat.postMessage for that.

Events API bots

If your bot user runs on the Events API, you can only toggle your bot's active or away status by managing your app and its Bot Users panel, or for apps published in the App Directory, on the Live App Settings panel.

Toggling bot user presence for the events API

When set to Off, your bot user is only marked as online if it's connected to the RTM API.

When set to On, your bot user will be marked as active and present. That green dot is all yours. Just toggle back Off again to be marked away.

Your bot user's profile will include a always_active field set to true. Counter-intuitively, your bot's presence field will remain away. That's the bad news.

The good news is that always_active will be interpreted by Slack clients as if the bot user's presence were active. Yes, you're awarded that green dot.

RTM bots

If your bot user runs on the RTM API, your bot will be marked active to users whenever connected to the RTM API.

Bots cannot set their presence to active with users.setPresence. RTM bots can use it to set it to away. Or you can always automatically mark your bot as away by disconnecting from your websocket.

Determining user presence

Batched presence events

Traditionally, using the Real Time Messaging API the initial call to rtm.start or rtm.connect would include the current presence value for every member of your team. If their presence value changes after that, a presence_change event would be sent.

On large teams — especially teams that are part of an Enterprise Grid, presence events can be batched together into a special version of the presence_change event that includes a users array instead of a singular user field. You'll need to opt-in to this behavior by passing the batch_presence_aware=true parameter to rtm.start or rtm.connect.

Presence subscriptions over RTM

Presence subscriptions allow you to receive only the presence events emitted by the users your app is concerned with. This is especially useful on large teams where it is infeasible to process every presence event for every user.

By passing a presence_sub=true parameter to rtm.start or rtm.connect, presence_change events will be withheld unless you subscribe to them.

Subscribe to presence_change events for specific users by sending a presence_sub event into the websocket.

For instance, to subscribe to presence_change events for users U123456 and W123456, I would write the following JSON blob into an established websocket:

{
    "type": "presence_sub",
    "ids": [
        "U123456",
        "W123456"
    ]
}

The message server will respond with presence_change events indicating the current presence state of any users added to the presence subscription.

Here's what you need to know about presence subscriptions:

  • You must declare your entire list of user IDs to subscribe to in each request.
    • Add users by appending them to your array of ids.
    • Remove users by removing them from your array of ids.
  • Subscribing to all user's presence events requires specifying every user's ID. This is not recommended, especially on large teams.
  • Presence subscriptions work best with bulk presence_change events.
  • Upon connecting, your app will have no presence subscriptions.
  • Presence subscriptions only last the duration of a websocket session. Disconnecting means needing to subscribe again.
  • By specifying an Enterprise Grid user ID belonging to a user on another team within the same Enterprise Grid, your app can subscribe to cross-team presence_change events.

Presence subscriptions are not required but strongly recommended.

Presence querying with the Web API

When using our Web API, you can call the users.getPresence method to get the user's current presence value.

Presence subscriptions over Events API

It is not currently possible to track presence-related events using the Events API.