Slack Presence API: users.getPresence and setPresence With Code

The Slack presence API is two Web API methods. users.getPresence returns whether a user is active or away and needs the users:read scope. users.setPresence sets the calling user's presence to away or back to auto, and needs users:write. There is no value that forces a user to active. To be told when presence changes, you need an RTM connection with a presence_sub subscription, because the Events API sends no presence events.

Everything on this page comes from Slack's developer docs, with code you can run. If you only want your own dot green during working hours, the FAQ at the end covers that; if you want to build or measure, read on.

Presence methods, scopes and rate limits

Presence and status are different things. To get a token first, see Slack bot token: how to get one. Presence is the green or grey dot. Status is the emoji and text next to a name. The difference is explained in Slack active status explained.

Get a user's presence with users.getPresence

With curl and a bot or user token that has users:read:

curl -s -H "Authorization: Bearer $SLACK_TOKEN" \
  "https://slack.com/api/users.getPresence?user=U0123ABCD"

For another user you get the presence only:

{"ok": true, "presence": "away"}

Leave out user and the method answers for the owner of the token, with the details of how Slack computed it:

{
  "ok": true,
  "presence": "active",
  "online": true,
  "auto_away": false,
  "manual_away": false,
  "connection_count": 1,
  "last_activity": 1419027078
}

• • online is true if the user has a client connected to Slack.
• • auto_away is true if Slack saw no activity from the user in the last 10 minutes.
• • manual_away is true if the user set themselves away.
• • connection_count counts connected clients.
• • last_activity is the last activity Slack's servers saw. It is missing when no client is connected.

How Slack decides active or away



Slack's docs define it in one line: a user is active if they have at least one client connected to Slack and they are not marked away. They are marked away in two ways. Automatic away happens after 10 minutes with no activity in the client. Manual away comes from the user or from users.setPresence, persists between connections, and overrides the automatic value. Bot users are exempt from auto-away.

"Activity" on desktop means keyboard or mouse input anywhere on the computer: the Slack desktop app reads the system idle time every 10 seconds and tickles Slack's server when it is under 20 seconds (Slack desktop 4.52.178 code, checked 7 Oct 2026). The device-level rules are in how Slack decides when you are away, and the timings are in how long does Slack stay active.

Get presence in Python with slack_sdk

Install the official SDK with pip install slack_sdk, then:

import os
from slack_sdk import WebClient
from slack_sdk.errors import SlackApiError

client = WebClient(token=os.environ["SLACK_TOKEN"])

try:
    res = client.users_getPresence(user="U0123ABCD")
    print(res["presence"])  # "active" or "away"
except SlackApiError as e:
    print("Slack error:", e.response["error"])  # e.g. missing_scope, invalid_auth

To check a team, loop over members from users.list and respect the Tier 3 limit. Slack answers with HTTP 429 and a Retry-After header when you go too fast; our rate limit test charts where that started for three methods:

import time

members = client.users_list()["members"]
people = [m for m in members if not m["is_bot"] and not m["deleted"] and m["id"] != "USLACKBOT"]

for m in people:
    while True:
        try:
            p = client.users_getPresence(user=m["id"])["presence"]
            print(m["name"], p)
            break
        except SlackApiError as e:
            if e.response.status_code == 429:
                time.sleep(int(e.response.headers.get("Retry-After", 30)))
            else:
                raise
    time.sleep(1.2)  # stay under about 50 calls a minute

Polling every person every few minutes is how "online hours" apps build a timesheet out of the dot. What that means for employees is in can Slack be used to monitor employees. A one-person version that DMs you when a coworker turns green is in get notified when someone comes online in Slack.

Set presence with users.setPresence

users.setPresence changes the calling user's manual presence. It accepts two values:

• away: mark yourself away until you set auto again.

• auto: hand the decision back to Slack's automatic rules.

curl -s -X POST -H "Authorization: Bearer $SLACK_USER_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"presence": "away"}' \
  https://slack.com/api/users.setPresence

client.users_setPresence(presence="auto")

There is no active value. Slack's docs say it directly: there is no way to force a user status to active. Why that breaks most keep-active scripts is in script to keep Slack active. auto only clears a manual away. If nothing is connected, or the client has been idle for 10 minutes, the user stays away. A green dot needs a connected client with activity, which is why tools that keep Slack active either feed input to a real client or hold a connected session. The session tokens that make a server-side client possible are covered in Slack xoxc and xoxd tokens.

Bot presence

Bots are different. A bot on the Events API cannot set itself active with the API. You turn Always Show My Bot as Online on in the app's settings, and the bot's profile then carries always_active: true. Its presence field still reads away, but Slack clients show it green. A bot on RTM is active while its websocket is connected and can set itself away.

Track presence changes in real time

The Events API has no presence events. For live changes you need the RTM API, which Slack now limits to classic apps:

Connect with rtm.connect and batch_presence_aware=1.

Send a presence_sub message listing every user ID you want, in each request:

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

Read presence_change events. With batching, one event carries a users array.

Slack's limits: subscriptions last only as long as the websocket, you must send the full list each time, and about 500 users is a sensible maximum. For a one-off lookup of up to 500 users, send presence_query instead. For new apps that cannot use RTM, polling users.getPresence is the only option.

Huddles have their own field and event, huddle_state and user_huddle_changed; see Slack huddle API.

Read and set custom status

Status lives in the user profile, not in presence:

profile = client.users_profile_get(user="U0123ABCD")["profile"]
print(profile["status_emoji"], profile["status_text"], profile["status_expiration"])

client.users_profile_set(profile={
    "status_text": "Focus time",
    "status_emoji": ":headphones:",
    "status_expiration": int(time.time()) + 2 * 3600,
})

status_text holds up to 100 characters, and status_expiration is a Unix timestamp; 0 means it never clears. Setting status needs a user token with users.profile:write. Admins on paid plans can set another user's status by passing user. To hear about status changes, subscribe to user_change in the Events API. Scheduling status without code is covered in how to schedule a Slack status. More status examples, reading and clearing, are in set a Slack status with the API.

FAQ

What scope does users.getPresence need?

users:read, with either a bot token or a user token.

Can the Slack API set a user to active?

No. users.setPresence accepts only auto and away. Active needs a connected client with recent activity.

Does the Slack Events API send presence_change?

No. Presence events are available only over RTM with a presence_sub subscription.

Why does users.getPresence say away when the person is working?

Slack counts only activity in the Slack client. After 10 minutes without it, auto_away turns true. See why Slack keeps showing you as away.

How do I keep my own Slack presence active on a schedule?

The API cannot force active: users.setPresence accepts only auto or away. Slack Green signs in to Slack on its side and keeps your presence active until your schedule ends, which the API alone cannot do.

Does Microsoft Teams have a presence API like this?

Yes, through Microsoft Graph. It reads status with GET /me/presence and sets it with setUserPreferredPresence; see the Microsoft Graph presence API.