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

Bot Users

You’re viewing documentation on legacy custom integrations, an older way for teams to build into their Slack team. To securely utilize the newest platform features like message buttons & the Events API, build internal integrations as part of a Slack app just for your team instead. Get started.

Enable teams to conversationally interact with external services or your custom code by building bot users.

A conversation between @celeste and @officebot

What are bot users?

Bot users have many of the same qualities as their human counterparts: they have profile photos, names, and bios, they exist in the team directory, they can be direct messaged or mentioned, they can post messages and upload files, and they can be invited to and kicked out of channels and private groups.

The biggest difference between bot users and regular users is that instead of interacting with a team via one of Slack's mobile or desktop apps, bot users are controlled programmatically via a bot user token that accesses one or more of Slack's APIs.

Bot users can't "log in," they don't have a password, and they only have access to a subset of all of the API methods available to regular users.

Within a Slack channel, bot users can do nearly anything you can program them to do.

Slack has two different kinds of bot users: custom bots and app bots. Each serves a different purpose and offers different functionality. This document concerns custom bots. To build an app bot, build a Slack app.

Custom bot users

Every team has the ability to create their own custom bot users that they can use on their team. They do this by going to their team's settings page and creating a new bot user.

Custom bot users are useful for when you want to build something custom for your own team, and have no interest in distributing it to other teams.

For example: you may want to do something very specific like send out an HR survey with a special link out to everyone at your company, or a way to listen for mentions of your company's dog mascot and post cute pictures whenever someone mentions his or her name.

What can bot users do?

The primary way bot users interact with people on a given team is by connecting to the Real Time Messaging API (RTM API for short) and opening up a websocket connection with Slack.

Monitor and process channel activity

This websocket will send you all of the messages and activity that happen in public and private channels that the bot user is invited to, as well as messages that are sent to it via direct message. A bot user opens this websocket with the RTM API by sending an authenticated call to the rtm.start API method. To learn more about connecting to the RTM API, read the documentation here.

Post messages and react to users

In addition to receiving messages and activity in the channels it belongs to, the RTM API can be used to post messages as well. However, the RTM API only supports posting messages in our default message formatting. It doesn't support attachments or other message formatting modes.

To post more complex messages as a bot user, clients can use the Web API methodchat.postMessage. Be sure and set as_user to true and use your bot user token.

The bot user can also use the Web API to add emoji reactions to messages, upload files, pin and star messages, and generally behave like any other user on the team.

Make messages interactive with buttons

Custom bots don't support message buttons. To make your messages interactive, you'll want to build a Slack app instead. Slack apps are easy to build and install just for your team.

An interactive message experience

Setting up your bot user

After you've figured out what you want your bot user to do and have an idea of how you'll go about implementing it, you'll want to prepare Slack for the arrival of your bot user.

How do I create custom bot users for my team?

Start by creating a new bot user integration. You'll need to pick a username for your new bot. Bot usernames can be up to 21 characters long and sorry, you can't name your bot Slackbot. Additionally, your bot username cannot be the same name as one of your team's channels.

Once you've added the integration to your team, you'll be granted a bot access token, which you'll use when connecting to our APIs as that bot user.

How do I distribute my bot user to other teams?

If you are the developer of an app or service that wants to provide bot-based functionality to Slack teams— or you just are working on something cool you want to share with everyone— you can package your bot user as a Slack app and implement the Slack button to make it simple for any team to install.

Programming bot users

Creating bot users probably means you'll be coding. If you're using an existing library (such as node-slack-client) then your bot access token should be all you need to get started.

If you're writing your own library from scratch, you'll need to write code to make authenticated API calls and consume our Real Time Messaging API. After building those basics, you can focus on the interesting functionality of your bot user.

Botkit

One easy way to build bot users, especially if you already work with Node.js, is Howdy's Botkit. Botkit is a framework that takes care of most these API gymnastics, so you can focus on your bot's behavior.

Other differences between bot users and normal users

  • pricing - Like other APIs and integrations, bot users are free. Unlike regular users, the actions they can perform are somewhat limited. For teams on the Free plan, each bot user counts as a separate integration.

  • account management - Bot user account management is performed through the integration page for the bot user.

  • presence - Bot users do not follow the usual rules for automatically being marked as away when inactive. In most cases you want a bot user to display as "active" and ready to respond, even if it hasn't posted a message in a while. Use the users.setPresence API method to set bot users as "away."

Share your bot user as a Slack app

Create a Slack app to package and distribute your bot user and submit it to our application directory.

Custom bot Web API methods

The full list of methods that can be used by bot users is:

Method & Description Description
api.test
Checks API calling code.
Checks API calling code.
auth.test
Checks authentication & identity.
Checks authentication & identity.
bots.info
Gets information about a bot user.
Gets information about a bot user.
channels.history
Fetches history of messages and events from a channel.
Fetches history of messages and events from a channel.
channels.info
Gets information about a channel.
Gets information about a channel.
channels.list
Lists all channels in a Slack team.
Lists all channels in a Slack team.
channels.mark
Sets the read cursor in a channel.
Sets the read cursor in a channel.
channels.replies
Retrieve a thread of messages posted to a channel
Retrieve a thread of messages posted to a channel
channels.setPurpose
Sets the purpose for a channel.
Sets the purpose for a channel.
channels.setTopic
Sets the topic for a channel.
Sets the topic for a channel.
chat.delete
Deletes a message.
Deletes a message.
chat.getPermalink
Retrieve a permalink URL for a specific extant message
Retrieve a permalink URL for a specific extant message
chat.meMessage
Share a me message into a channel.
Share a me message into a channel.
chat.postEphemeral
Sends an ephemeral message to a user in a channel.
Sends an ephemeral message to a user in a channel.
chat.postMessage
Sends a message to a channel.
Sends a message to a channel.
chat.update
Updates a message.
Updates a message.
conversations.close
Closes a direct message or multi-person direct message.
Closes a direct message or multi-person direct message.
conversations.history
Fetches a conversation's history of messages and events.
Fetches a conversation's history of messages and events.
conversations.info
Retrieve information about a conversation.
Retrieve information about a conversation.
conversations.list
Lists all channels in a Slack team.
Lists all channels in a Slack team.
conversations.members
Retrieve members of a conversation.
Retrieve members of a conversation.
conversations.open
Opens or resumes a direct message or multi-person direct message.
Opens or resumes a direct message or multi-person direct message.
conversations.replies
Retrieve a thread of messages posted to a conversation
Retrieve a thread of messages posted to a conversation
conversations.setPurpose
Sets the purpose for a conversation.
Sets the purpose for a conversation.
conversations.setTopic
Sets the topic for a conversation.
Sets the topic for a conversation.
dialog.open
Open a dialog with a user
Open a dialog with a user
dnd.info
Retrieves a user's current Do Not Disturb status.
Retrieves a user's current Do Not Disturb status.
dnd.teamInfo
Retrieves the Do Not Disturb status for users on a team.
Retrieves the Do Not Disturb status for users on a team.
emoji.list
Lists custom emoji for a team.
Lists custom emoji for a team.
files.comments.add
Add a comment to an existing file.
Add a comment to an existing file.
files.comments.delete
Deletes an existing comment on a file.
Deletes an existing comment on a file.
files.comments.edit
Edit an existing file comment.
Edit an existing file comment.
files.delete
Deletes a file.
Deletes a file.
files.info
Gets information about a team file.
Gets information about a team file.
files.upload
Uploads or creates a file.
Uploads or creates a file.
groups.history
Fetches history of messages and events from a private channel.
Fetches history of messages and events from a private channel.
groups.info
Gets information about a private channel.
Gets information about a private channel.
groups.list
Lists private channels that the calling user has access to.
Lists private channels that the calling user has access to.
groups.mark
Sets the read cursor in a private channel.
Sets the read cursor in a private channel.
groups.open
Opens a private channel.
Opens a private channel.
groups.setPurpose
Sets the purpose for a private channel.
Sets the purpose for a private channel.
groups.setTopic
Sets the topic for a private channel.
Sets the topic for a private channel.
im.close
Close a direct message channel.
Close a direct message channel.
im.history
Fetches history of messages and events from direct message channel.
Fetches history of messages and events from direct message channel.
im.list
Lists direct message channels for the calling user.
Lists direct message channels for the calling user.
im.mark
Sets the read cursor in a direct message channel.
Sets the read cursor in a direct message channel.
im.open
Opens a direct message channel.
Opens a direct message channel.
im.replies
Retrieve a thread of messages posted to a direct message conversation
Retrieve a thread of messages posted to a direct message conversation
migration.exchange
For Enterprise Grid workspaces, map local user IDs to global user IDs
For Enterprise Grid workspaces, map local user IDs to global user IDs
mpim.close
Closes a multiparty direct message channel.
Closes a multiparty direct message channel.
mpim.history
Fetches history of messages and events from a multiparty direct message.
Fetches history of messages and events from a multiparty direct message.
mpim.list
Lists multiparty direct message channels for the calling user.
Lists multiparty direct message channels for the calling user.
mpim.mark
Sets the read cursor in a multiparty direct message channel.
Sets the read cursor in a multiparty direct message channel.
mpim.open
This method opens a multiparty direct message.
This method opens a multiparty direct message.
oauth.access
Exchanges a temporary OAuth code for an API token.
Exchanges a temporary OAuth code for an API token.
oauth.token
Exchanges a temporary OAuth verifier code for a workspace token.
Exchanges a temporary OAuth verifier code for a workspace token.
pins.add
Pins an item to a channel.
Pins an item to a channel.
pins.list
Lists items pinned to a channel.
Lists items pinned to a channel.
pins.remove
Un-pins an item from a channel.
Un-pins an item from a channel.
reactions.add
Adds a reaction to an item.
Adds a reaction to an item.
reactions.get
Gets reactions for an item.
Gets reactions for an item.
reactions.list
Lists reactions made by a user.
Lists reactions made by a user.
reactions.remove
Removes a reaction from an item.
Removes a reaction from an item.
rtm.connect
Starts a Real Time Messaging session.
Starts a Real Time Messaging session.
rtm.start
Starts a Real Time Messaging session.
Starts a Real Time Messaging session.
stars.add
Adds a star to an item.
Adds a star to an item.
stars.remove
Removes a star from an item.
Removes a star from an item.
team.info
Gets information about the current team.
Gets information about the current team.
users.getPresence
Gets user presence information.
Gets user presence information.
users.info
Gets information about a user.
Gets information about a user.
users.list
Lists all users in a Slack team.
Lists all users in a Slack team.
users.lookupByEmail
Finds information about a user by email address.
Finds information about a user by email address.
users.setActive
Marks a user as active.
Marks a user as active.
users.setPresence
Manually sets user presence.
Manually sets user presence.

You can tell if a user object returned by our API is a bot user by checking the is_bot property.