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

Batching presence events and presence subscriptions in the RTM API

Updated: 2017-06 APIs

If you've been developing on Slack for awhile you may have noticed a continued theme with updates we make to the platform and APIs: larger teams and evolving use cases mean previous ways of enumerating collections of data become unwieldy and even problematic.

In this exciting edition of the changelog, I'd like to introduce you to new ways to work with presence_change events in the RTM API.

If you don't work with the RTM API or don't utilize presence_change events, there's very little of value for you in this changelog.

What's changing?

We're introducing two new scalable ways to stay on top of presence change notices in the RTM API.

1. Batched presence events

On large teams especially, folks flock like birds and change their presence at the same time to the same things.

Both to help us dispatch these and for you to consume these reliably, we've introduced a batch_presence_aware=true parameter to pass to rtm.start or rtm.connect. Doing so indicates you can receive batched presence events.

These are the presence_change events you're used to except instead of a single user field, you'll find a users field with an array of user IDs.

2. Presence subscriptions

Maybe your app only needs to know the presence of like five people on a team of thousands. Or five hundred people. Or maybe you need all of those thousands.

Well instead of having no choice but to receive them all, now you can send a presence_sub=true parameter to rtm.start and rtm.connect and you'll tell us that you only want presence_change events for users you're establishing subscriptions for.

You then push presence_sub, a write-only event, into the websocket and declare a list of users to subscribe to. There's some more nuance to it that the presence docs cover for you.

Once subscribed, you'll only get those users' presence_changed events. Subscriptions last only the length of an open websocket connection.

What isn't changing?

The Events API isn't changing how it handles user presence events — it still stubbornly doesn't support them at all!

You won't receive bulk presence_change events if you don't opt-in to them using the batch_presence_aware=true parameter with rtm.start or rtm.connect.

You won't need to subscribe to presence_change events with presence_sub unless you opt-in to subscription using the presence_sub=true parameter with rtm.start or rtm.connect.

What happens if I do nothing?

If you don't use the RTM API or don't use presence_change events — nothing. Do nothing and nothing also happens. Easy.

On very large teams, like Enterprise Grid teams, you might miss some presence_change events if you don't batch them up. Or you might receive so many at one time that your app blows up.

If you don't use presence_sub to manage a smaller concern of presence_change events you might receive so many at one time that your bot forgets its name.

How do I prepare?

If you want to go "all-in" with both subscriptions and batching, you'll want to do all of the following:

  1. Read the docs and decide if these features are right for you.
  2. Opt-in to the features by providing the appropriate parameters when preparing to connect to the RTM API
  3. Anticipate receiving presence_change events with a users array instead of a user string, and subscribe to these changes using presence_sub.

When is this happening?

These new features are available now. Our concern with very large teams is clear and present. Implement them at your leisure, but if you work with Enterprise Grid teams you may want to migrate sooner than later.

If you have any questions or concerns, please contact us.

Review other recent updates