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 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:


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 active. 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. A manual active presence set using this method indicates that the automatic status should be used instead.

Fetching user presence

When using the Real Time Messaging API the initial call to rtm.start will include the current presence value for every member of your team. If their presence value changes a presence_change event will be sent.

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

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.