Manipulate Presence

Learn to use Slack API calls to manipulate presence.

We'll cover the following

We’ll cover the following endpoints from Slack’s Users API in this lesson.

  1. users.setPresence: This endpoint manually sets user presenceThis is a flag with the value of either “auto” or “away.” When it is set to “away,” the user is shown as non-active..
  2. users.getPresence: This endpoint gets user presence information.

Retrieve a user token

Even though our application can set its presence with our current token, this isn’t that useful because no user can see the application’s “activity” status. It’ll be a lot more useful if a user could manipulate their presence, and to do that, we’ll need a user tokenThis is a string of characters that third parties can use to authenticate a request on a user’s behalf.. To get the user token, follow the steps below:

  1. Go to Slack’s API website and click on your application.
  2. Go to the “OAuth & Permissions” tab on the left-hand sidebar.
  3. Now scroll down and click the “Add an OAuth Scope” for the “User Token Scopes.”
  4. Give the application the following scopes: users:read and users:write.
  5. Click “reinstall your app” on the yellow notification.
  6. Click the “Allow” button and copy the “User OAuth Token.”
  7. Paste it in the code widget below.

Set the user’s presence

To set the user’s presence, we access the https://slack.com/api/users.setPresence endpoint. This endpoint allows us to set presence manually.

Request parameters

Some important query parameters for the users.setPresence endpoint are as follows:

Parameter

Type

Category

Description

token

token

required

Authentication tokens carry the required scopes that govern the usage of different Slack applications and APIs. We usually pass these tokens as an HTTP Authorization header or as a POST parameter.

presence

string

required

This can be set to either auto or away.

Let’s call the users.setPresence endpoint. Click the “Run” button to set the presence as “away” for yourself.

Press + to interact
Javascript (babel-node)
import fetch from "node-fetch";
const url = new URL("https://slack.com/api/users.setPresence");
const headerParameters = {
  Authorization: "Bearer {{USER_TOKEN}}",
  "Content-Type": "application/json; charset=UTF-8",
};
const bodyParameters = JSON.stringify({
  presence: "away",
});
const options = {
  method: "POST",
  headers: headerParameters,
  body: bodyParameters,
};
async function setPresence() {
  try {
    const response = await fetch(url, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
setPresence();

On line 11, we set the presence as away and call the users.setPresence endpoint on line 22.

Response fields

The response from this endpoint only contains the ok field indicating whether or not the request was successful.

Note: After running the code above, you should notice yourself as being set as “away” in the Slack application.

Get the user’s presence

To get the user’s presence, we access the https://slack.com/api/users.getPresence endpoint.

Request parameters

Some important query parameters for the users.getPresence endpoint are as follows:

Parameter

Type

Category

Description

token

token

required

Authentication tokens carry the required scopes that govern the usage of different Slack applications and APIs. We usually pass these tokens as an HTTP Authorization header or as a POST parameter.

user

string

optional

This is the user ID of the user whose presence will be retrieved.

Let’s call the users.getPresence endpoint. Click the “Run” button to get the current presence of a user.

Press + to interact
Javascript (babel-node)
import fetch from "node-fetch";
const url = new URL("https://slack.com/api/users.getPresence");
const headerParameters = {
  Authorization: "Bearer {{USER_TOKEN}}",
  "Content-Type": "application/json; charset=UTF-8",
};
const options = {
  method: "GET",
  headers: headerParameters,
};
async function getPresence() {
  try {
    const response = await fetch(url, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
getPresence();

On line 17, we call the user.getPresence endpoint to get the presence we set in the previous widget.

Response fields

Some of the important fields included in a successful response from this endpoint are as follows:

Parameter

Type

Description

ok

boolean

A boolean value indicating whether the request was successful or not.

presence

string

The authorized user's current presence status. It can either be auto or away.

online

boolean

Whether the authorized user is currently online or not.

auto_away

boolean

Whether the user's presence was automatically set to away.

manual_away

boolean

Whether the user's presence was manually set to away.

last_activity

string

A timestamp of when the user was last active.