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

Enable workspaces 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 workspace 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 workspace 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.

Custom bot users

Every workspace has the ability to create their own custom bot users that they can use on their workspace. They do this by going to their workspace'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 workspace, and have no interest in distributing it to other workspaces.

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.

Attaching bot users to a Slack app

If you'd like to distribute your bot user to other Slack workspaces, then you should attach it to a Slack app. This makes it much easier for workspaces to install via the Slack Button, lets you control the bot user's icon and name even after it has been installed, and allows you to bundle it with other app functionality like incoming webhooks and slash commands.

Bot users in Slack apps have some special considerations when using the API.

What can bot users do?

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

The Events API is an alternative way to receive and respond to events as a bot user contained within a Slack App. Instead of connecting over a websocket, you subscribe to specific events and messages and Slack sends them to your server.

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.connect 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 method chat.postMessage. Set as_user to true to send messages as your bot with its username and profile image.

Alternatively, chat.postEphemeral method allows a bot user to post a complex message visible only to a specific user and context.

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 workspace.

Bots can also work within threaded messages and add replies to conversations.

Make messages interactive with buttons

Bot users wrapped in Slack apps can attach buttons to messages. These buttons trigger actions on your servers, allowing your bot to perform distinct tasks and incrementally alter messages.

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 workspace?

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 workspace's channels.

Once you've added the integration to your workspace, 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 workspaces?

If you are the developer of an app or service that wants to provide bot-based functionality to Slack workspaces— 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 workspace 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 workspaces 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 users.setPresence to set bot users as "away."

There's more to learn about making your bot present in our bot user presence documentation.

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.

Tokens and scopes

When workspaces add your application and install your bot user, the token belonging to your bot user is imbued with the necessary scopes to use API methods on its own behalf for the workspace that is installing your bot user.

You may have other OAuth tokens associated with your app or specific users who have authorized it. Those tokens have a time and place, but when you want to use the Web or RTM API as the bot user, you must use the bot access token that has been awarded the bot scope. Bot user tokens begin with the characters xoxb.

Retrieving your bot user token

You'll receive workspace-specific bot tokens as part of the OAuth approval process. Once the team uses the Slack button to install your bot user and as you exchange the code for an access token, you'll receive an additional component to the typical access token response:

{
    "access_token": "xoxp-XXXXXXXX-XXXXXXXX-XXXXX",
    "scope": "incoming-webhook,commands,bot",
    "team_name": "Team Installing Your Hook",
    "team_id": "XXXXXXXXXX",
    "incoming_webhook": {
        "url": "https://hooks.slack.com/TXXXXX/BXXXXX/XXXXXXXXXX",
        "channel": "#channel-it-will-post-to",
        "configuration_url": "https://teamname.slack.com/services/BXXXXX"
    },
    "bot":{
        "bot_user_id":"UTTTTTTTTTTR",
        "bot_access_token":"xoxb-XXXXXXXXXXXX-TTTTTTTTTTTTTT"
    }
}

The bot node of that JSON response contains two fields. bot_user_id is the Slack user ID for your bot user on that workspace/team. The bot_access_token is the OAuth access token you must use when acting on behalf of your bot for that workspace.

Secure your bot user tokens, as with all tokens and credentials. Do not share tokens with users or anyone else. Bot user tokens have particularly expansive capabilities not afforded to typical user tokens issued on behalf of members.

API usage

As mentioned above, when you connect to the Real Time Messaging API or other APIs in the agency of your bot user, you'll need to use your bot user's OAuth token, awarded to you when somebody in your workspace authorizes your application.

Bot users can also only call a subset of our API methods. Any method that cannot be used by a bot user will return a user_is_bot error.

Bot users associated with Slack apps are granted access to fewer API methods than those in custom integrations.

If your Slack app needs access to additional methods in the Web API, you'll need to request your required scopes separately as part of the authentication flow. Additionally requested scopes are applied to your application tokens but will not be applied to your bot user tokens.

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

Method & Description Description Custom Bots App Bots
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.