How To Set Up Partner Bot

This article describes an outdated approach to Slack apps. New Slack apps act independently of a user token. Build a bot user powered by simply the specific permissions it needs. Cheque out new Slack apps now.

Enable conversations between users and apps in Slack by building bots.

A conversation between @celeste and @officebot

What are Bots?
Getting Started
- Creating a bot user
- Setting up the Events API
- Installing the bot to a workspace
- Handling events
  - Receiving events
  - Responding to mentions using the Spider web API
  - Responding to other messages
Making more complex bots
Limitations
- API methods available to bots

What are bots?

A bot is a type of Slack App designed to interact with users via conversation.

A bot is the aforementioned as a regular app: it can access the same range of APIs and do all of the magical things that a Slack App tin practice.

But when you build a bot for your Slack App, you're giving that app a face, a name, and a personality, and encouraging users to talk to it.

Your bot can send DMs, it tin can be mentioned by users, information technology can mail messages or upload files, and it can be invited to channels - or kicked out.

Bots are not cybernetic infiltration units, and it is unlikely that they dream of electrical sheep, though we can't rule it out. 🤖

Getting Started

Since your bot is capable of doing everything that a Slack App tin do, we're going to limit our focus to a mutual use-example for bots. The following steps will get you to the point where you take a bot waiting for messages with trigger words and sending simple responses.

From at that place, y'all can start bolting on any kind of astonishing app logic or nuclear-powered jet-packs you tin can imagine.

Earlier you start, you'll need a Slack App. If you don't already have one, click the post-obit push to create information technology:

Create your Slack app

That washed, you're all ready to arrange the architecture of this automaton.

1. Creating a bot user

To employ your Slack App equally a bot, get-go you lot'll demand to create a Bot User for it.

Head to your app'south settings page and click the Bot Users feature in the navigation menu.

Y'all'll be presented with a push marked Add a Bot User, and when you click on information technology, you'll see a screen where you lot tin can configure your app's bot user with the post-obit info:

Brandish proper noun - the name that is displayed to other users when the bot posts messages, or the bot'southward profile is viewed, etc.
Default username - the string that is used when the bot is mentioned in a message. This username may exist modified slightly from the default when it is installed to a workspace where that username is already reserved. This modification is an incrementing number appended to the username - and so @username might become @username2.
Always Show My Bot as Online - we recommend you enable this characteristic, so that your bot always appears to be ready to receive input (which information technology probably volition exist). When disabled, you'll have to programmatically set its online presence.

Once you lot've completed these fields, click the Add Bot User button and so Save Changes.

Great, you've but created a bouncing baby bot! Don't leave the app settings however though, at that place's just ane more bit of configuration left to do.

ii. Setting upwardly the Events API

The Events API is a bot'due south equivalent of eyes and ears. Information technology gives a bot a way to react to posted messages, changes to channels, and other activities that happen in Slack. When these events happen, a data payload volition be sent to your bot, and information technology tin can use that data to form a useful response.

Giving your bot admission to the Events API is pretty simple:

From your app's settings, click the Event Subscriptions feature in the navigation menu.
Switch the Enable Events toggle to on and yous'll exist presented with a new screen of options.
You'll need to configure the Request URL that the data payloads will exist pushed to. This URL needs to be verified get-go, as outlined in the Events API docs.
Then you'll add some private issue subscriptions. For our bot, we're interested in the Bot Events, then click on the Add Bot User Outcome push button.
At that place are lots of different event types you could add, only for the purposes of our tutorial let's add together two event subscriptions - app_mention which sends events when someone mentions your bot, and message.channels which sends events when a new bulletin is posted in a public channel.
Click the Save Changes buttons

Expert news! Your bot is looking more than and more life-like, and now it's fix to find a domicile.

3. Installing the bot to a workspace

A bot user is added to a workspace by installing the app that the bot is associated with. In one case you exercise, you'll get a bot token that is imbued with the bot telescopic. This token can exist used with a subset of Spider web API methods that we'll discuss later.

If you had already installed your app in the past, you'll demand to reinstall to grant the boosted bot scope. The process is the same either way:

On your app'south settings page again, click the Install App settings item in the navigation card.
On this page, click a push button marked Install App to your Workspace. If you had already installed your app, the push button to click will instead be marked Reinstall App.
You'll encounter a permissions authorization page, where you lot should click Qualify. Your app is now installed to that workspace, just you still need to invite it into private channels.
You lot should as well invite the bot to a public channel somewhere in your workspace.

Once installed, you will have generated a bot token that you should store for apply later on - yous can discover it in your app's settings under Install App > Bot User OAuth Access Token.

Bot tokens can too be generated using the OAuth install flow if y'all are distributing your app beyond your ain workspace.

Your bot should now be happily abode in the channel picked during the install procedure. It will be listening out for users posting in that channel, and for posted messages that mention the bot. Now you need to tell information technology what to do when it hears something.

4. Handling events

In a previous step, nosotros configured the consequence subscriptions for your app, but at present we have to actually exercise something with the data that will be sent with each upshot.

Let'south imagine a unproblematic conversational bot that responds to being mentioned past sending a couple of follow up letters:

Example conversation between a user and a bot with the user asking the bot to tell a joke

There are iv events triggered in this conversation: the beginning is an app_mention event from the first message that mentions the bot; the adjacent iii are message events for each of the messages posted by Johnny.

Our bot will need to exist able to interpret each event and answer appropriately.

Nosotros've avoided showing you whatever specific code up until now, but in the post-obit steps we're going to explain the process and so show very simplified Express/Node.js examples of what your app logic should look like. These examples translate readily into nearly modernistic programming languages.

Receiving events

The first thing we demand to exercise is create some app lawmaking that will correctly receive the events.

Each outcome volition trigger a request, containing a JSON payload, sent to your configured Request URL. The Events API docs incorporate a full description of the shape of this JSON, and the reference for app_mention and the message.channels comprise any details specific to each event blazon.

Your app has to be able to receive and parse this JSON, and and then transport an immediate confirmation response to each event request, as described in the Events API docs.

Hither's how we might build our lawmaking for receiving events:

          // Receive issue payload to Request URL via HTTP Mail service router.post("/", function(req, res, next) {     // Get event payload     let payload = req.body;     // Reply to this event with HTTP 200 condition     res.sendStatus(200); }

At present that you've written code to handle an event, you tin think about how to respond in a 'bot-like' way.

Responding to mentions using the Web API

For a bot, beingness mentioned is unremarkably the triggering event for a conversation, only as a human volition respond when they hear their name.

Your app code should use the type field within the consequence payload to spot these app_mention events, and differentiate them from any other events information technology might receive.

In addition, you don't desire to answer to every mention, but the ones that are actually intended to trigger the "tell a joke" flow.

To exercise that, utilise the text field from the event payload, which contains the text of the message that the mention was contained in. When text mentions the bot and includes the words "tell me a joke", the bot will answer; otherwise it'll only stay tranquility.

Here's what the example lawmaking might await similar with this kind of logic:

          router.postal service("/", function(req, res, side by side) {     let payload = req.trunk;     res.sendStatus(200);      if (payload.event.type === "app_mention") {         if (payload.upshot.text.includes("tell me a joke")) {             // Make call to chat.postMessage using bot'south token         }     } }

With the call to chat.postMessage, the offset line of the joke is sent:

          Knock, knock.

To send this, your app should use that API method with the token you stored earlier. Here's an case request:

          POST https://slack.com/api/chat.postMessage Content-blazon: application/json Authorization: Bearer YOUR_BOTS_TOKEN {     "text": "Hello <@UA8RXUPSP>! Knock, knock.",     "channel": "CBR2V3XEX" }

You can read the API method reference for more info on building this request. You can, of class, utilise all the special formatting, attachments, and interactive components bachelor for messages, just for now go along it simple.

So, your bot has uttered those first magical words, and you can assume that the user will reply with the standard "Who's there?" response. Let's detect out how to go on the joke going.

Responding to other messages

As we said before, the menstruum we're describing contains an app_mention event followed by three message events. In order to place the differences between those iii letters, the app logic must become a bit more complex.

The showtime matter you demand to practise is use the type field within the consequence payload to look for these message events.

Side by side, use the text of the message in the result payload to determine which kind of response your bot should make.

Once more, let's assume the pattern of 'knock, knock' jokes - the beginning user response is always "Who's there?", and the second user response is always "____ who?". And then, you tin check for letters that include these words, and use the right bot response for each. If you run into any messages that don't include either of these phrases, ignore them.

Added to the lawmaking from previous steps you'll have something like this:

          router.postal service("/", part(req, res, next) {     let payload = req.body;     res.sendStatus(200);      if (payload.upshot.blazon === "app_mention") {         if (payload.event.text.includes("tell me a joke")) {             // Make call to conversation.postMessage using bot'southward token         }     }     if (payload.event.type === "message") {         let response_text;         if (payload.event.text.includes("Who's there?")) {             response_text = "A bot user";         }         if (payload.event.text.includes("Bot user who?")) {             response_text = "No, I'yard a bot user. I don't sympathize jokes.";         }         if (response_text !== undefined) {             // Make call to chat.postMessage sending response_text using bot's token         }     } }

Congratulations, your beginning bot is at present live and talking! You should now be able to go to the channel you installed the bot into and strike up this chat with it. Recall to laugh politely when it tells you lot the punchline.

Your next steps should involve adding some more complexity to your bot to make information technology useful.

Making more circuitous bots

In the steps above, nosotros made a lot of assumptions of simplicity. For example, we expected that users would reply with a very specific spelling, we assumed a exam environment where there were no other conversations happening, and then on.

For a real bot in production, some of these assumptions would break the beliefs of the bot. So let's embrace some situations that you lot should accost for your ain bots - remember of these as best practices rather than specific instructions to follow.

Tracking conversations

In our instance bot, nosotros've used a mention as the triggering indicate for a specific conversation, but you'll discover that your bot volition even so respond if y'all skip some of the steps - for example if yous type Who's at that place?, your bot will answer to this message with A bot user, even if you didn't mention the bot or start at the beginning of the conversation.

A solution to this might involve tracking the beginning of a conversation, the participants involved, and the progress through the flow. For example, when the user first mentions the bot, a database entry is created that identifies that user and the open workflow with them.

As the user progresses through the period, the database records this, and the user is unable to repeat earlier steps in the chat (unless of course that is a desired beliefs). Once the workflow is completed, the database entry is also marked equally complete, and the bot waits for some other mention before starting anew.

Threaded letters

Exist aware that a user might choose to reply to your bot's messages in a thread rather than at the aqueduct-level. Your bot volition still receive bulletin events for these threaded replies, merely you volition have to add some extra logic to ensure that your bot responds to the user in the relevant location.

Check out the Threading Messages docs for more data on how to spot the deviation between messages and threaded letters.

Variations in phrasing

Because your bot will be interacting with humans, information technology'southward unlikely that you can expect consistent spelling and phrasing across messages from different people that might be trying to invoke the same thing. For example, our simple example bot used the phrase tell me a joke to trigger the start of the workflow, merely at a very basic level a user might too attempt typing what's a good joke? or brand me express mirth.

Your bot can get more than complex past broadening its understanding of natural language queries to capture a wider range of potential trigger phrases. Alternatively you lot tin can exist more prescriptive about the verbal phrasing to employ, and provide user instruction to train correct usage.

Integrating with other services

The existent magic of a bot comes when it is connected with external services, providing a seamless conversational interface for them from within Slack.

There's a huge range of possibilities for what your bot could do, then it might help to start with a keen resource like the Botkit Community.

Limitations

Like other APIs and integrations, bot users are costless. Unlike regular users, the actions they tin can perform are somewhat limited. For workspaces on the Free plan, each bot user counts equally a separate integration.

API methods available to bots

Bot Users, and bot tokens, tin can exist used with a slightly restricted set of Web API methods. These methods are shown below:

Methods for the modern bot

Method & Description	Description
apps.uninstall Uninstalls your app from a workspace.	Uninstalls your app from a workspace.
auth.revoke Revokes a token.	Revokes a token.
auth.teams.list List the workspaces a token can access.	Listing the workspaces a token can access.
auth.exam Checks hallmark & identity.	Checks authentication & identity.
bookmarks.add Add bookmark to a channel.	Add bookmark to a channel.
bookmarks.edit Edit bookmark.	Edit bookmark.
bookmarks.list List bookmark for the channel.	List bookmark for the channel.
bookmarks.remove Remove bookmark from the channel.	Remove bookmark from the aqueduct.
bots.info Gets data most a bot user.	Gets data most a bot user.
calls.add Registers a new Telephone call.	Registers a new Call.
calls.end Ends a Call.	Ends a Telephone call.
calls.info Returns information about a Call.	Returns data nearly a Telephone call.
calls.participants.add Registers new participants added to a Call.	Registers new participants added to a Call.
calls.participants.remove Registers participants removed from a Call.	Registers participants removed from a Call.
calls.update Updates information about a Call.	Updates data well-nigh a Call.
channels.create Creates a channel.	Creates a channel.
channels.info Gets information well-nigh a channel.	Gets information about a channel.
channels.invite Invites a user to a aqueduct.	Invites a user to a aqueduct.
channels.mark Sets the read cursor in a aqueduct.	Sets the read cursor in a channel.
conversation.delete Deletes a message.	Deletes a message.
chat.deleteScheduledMessage Deletes a awaiting scheduled message from the queue.	Deletes a pending scheduled bulletin from the queue.
chat.getPermalink Call back 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 bulletin to a user in a channel.
chat.postMessage Sends a bulletin to a channel.	Sends a message to a aqueduct.
chat.scheduleMessage Schedules a message to be sent to a channel.	Schedules a message to be sent to a channel.
conversation.scheduledMessages.list Returns a list of scheduled messages.	Returns a listing of scheduled messages.
chat.unfurl Provide custom unfurl behavior for user-posted URLs	Provide custom unfurl behavior for user-posted URLs
chat.update Updates a message.	Updates a message.
conversations.acceptSharedInvite Accepts an invitation to a Slack Connect channel.	Accepts an invitation to a Slack Connect aqueduct.
conversations.approveSharedInvite Approves an invitation to a Slack Connect channel	Approves an invitation to a Slack Connect aqueduct
conversations.archive Archives a conversation.	Archives a conversation.
conversations.close Closes a direct message or multi-person directly bulletin.	Closes a direct bulletin or multi-person direct message.
conversations.create Initiates a public or private channel-based conversation	Initiates a public or private channel-based chat
conversations.declineSharedInvite Declines a Slack Connect aqueduct invite.	Declines a Slack Connect aqueduct invite.
conversations.history Fetches a chat's history of messages and events.	Fetches a conversation's history of letters and events.
conversations.info Retrieve information nigh a conversation.	Call up data about a conversation.
conversations.invite Invites users to a channel.	Invites users to a channel.
conversations.inviteShared Sends an invitation to a Slack Connect channel	Sends an invitation to a Slack Connect channel
conversations.join Joins an existing conversation.	Joins an existing conversation.
conversations.boot Removes a user from a conversation.	Removes a user from a conversation.
conversations.leave Leaves a conversation.	Leaves a conversation.
conversations.list Lists all channels in a Slack team.	Lists all channels in a Slack team.
conversations.listConnectInvites Lists shared channel invites that accept been generated or received but have not been approved by all parties	Lists shared aqueduct invites that have been generated or received but accept not been approved past all parties
conversations.mark Sets the read cursor in a channel.	Sets the read cursor in a aqueduct.
conversations.members Retrieve members of a chat.	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.rename Renames a conversation.	Renames a conversation.
conversations.replies Retrieve a thread of messages posted to a chat	Retrieve a thread of letters posted to a chat
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.
conversations.unarchive Reverses conversation archival.	Reverses conversation archival.
dialog.open Open a dialog with a user	Open a dialog with a user
dnd.info Retrieves a user'south current Do Not Disturb status.	Retrieves a user's current Practise Not Disturb condition.
dnd.teamInfo Retrieves the Do Not Disturb condition for up to 50 users on a squad.	Retrieves the Exercise Not Disturb condition for up to fifty users on a team.
emoji.list Lists custom emoji for a team.	Lists custom emoji for a squad.
files.comments.delete Deletes an existing annotate on a file.	Deletes an existing annotate on a file.
files.delete Deletes a file.	Deletes a file.
files.info Gets information about a file.	Gets information about a file.
files.listing List for a team, in a channel, or from a user with applied filters.	Listing for a squad, in a aqueduct, or from a user with practical filters.
files.remote.add Adds a file from a remote service	Adds a file from a remote service
files.remote.info Retrieve information about a remote file added to Slack	Retrieve data well-nigh a remote file added to Slack
files.remote.list Think information about a remote file added to Slack	Call up data most a remote file added to Slack
files.remote.remove Remove a remote file.	Remove a remote file.
files.remote.share Share a remote file into a channel.	Share a remote file into a channel.
files.remote.update Updates an existing remote file.	Updates an existing remote file.
files.upload Uploads or creates a file.	Uploads or creates a file.
groups.create Creates a individual channel.	Creates a private channel.
groups.info Gets information well-nigh a private channel.	Gets information about a private channel.
groups.invite Invites a user to a individual channel.	Invites a user to a private aqueduct.
groups.marking Sets the read cursor in a individual aqueduct.	Sets the read cursor in a private aqueduct.
groups.open Opens a individual channel.	Opens a individual channel.
im.list Lists direct message channels for the calling user.	Lists directly message channels for the calling user.
im.mark Sets the read cursor in a direct message channel.	Sets the read cursor in a direct bulletin aqueduct.
im.open Opens a direct message channel.	Opens a direct message channel.
migration.commutation 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.list Lists multiparty direct message channels for the calling user.	Lists multiparty straight bulletin 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 straight message.	This method opens a multiparty direct message.
pins.add Pins an item to a aqueduct.	Pins an detail to a channel.
pins.list Lists items pinned to a channel.	Lists items pinned to a aqueduct.
pins.remove United nations-pins an detail from a aqueduct.	United nations-pins an item from a channel.
reactions.add Adds a reaction to an item.	Adds a reaction to an particular.
reactions.go 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 detail.	Removes a reaction from an particular.
stars.add Save an detail for later. Formerly known every bit _adding a star_.	Salvage an item for subsequently. Formerly known every bit _adding a star_.
team.billing.info Reads a workspace'southward billing plan information.	Reads a workspace's billing plan information.
team.info Gets information most the current squad.	Gets data about the electric current team.
team.preferences.list Call up a list of a workspace'due south team preferences.	Retrieve a list of a workspace'southward team preferences.
team.profile.go Retrieve a squad'southward profile.	Call up a team'due south profile.
usergroups.create Create a User Grouping	Create a User Group
usergroups.disable Disable an existing User Group	Disable an existing User Group
usergroups.enable Enable a User Group	Enable a User Grouping
usergroups.list List all User Groups for a team	Listing all User Groups for a team
usergroups.update Update an existing User Group	Update an existing User Group
usergroups.users.list List all users in a User Group	List all users in a User Group
usergroups.users.update Update the list of users for a User Grouping	Update the list of users for a User Group
users.conversations List conversations the calling user may access.	Listing conversations the calling user may access.
users.getPresence Gets user presence information.	Gets user presence information.
users.info Gets information about a user.	Gets information nearly a user.
users.list Lists all users in a Slack team.	Lists all users in a Slack team.
users.lookupByEmail Notice a user with an email address.	Find a user with an electronic mail accost.
users.contour.get Retrieve a user's contour information, including their custom status.	Retrieve a user'south contour information, including their custom condition.
users.setActive Marked a user every bit active. Deprecated and not-functional.	Marked a user as active. Deprecated and non-functional.
users.setPresence Manually sets user presence.	Manually sets user presence.
views.open up Open a view for a user.	Open a view for a user.
views.publish Publish a static view for a User.	Publish a static view for a User.
views.push button Push a view onto the stack of a root view.	Push a view onto the stack of a root view.
views.update Update an existing view.	Update an existing view.
workflows.stepCompleted Point that an app's step in a workflow completed execution.	Indicate that an app's pace in a workflow completed execution.
workflows.stepFailed Signal that an app's stride in a workflow failed to execute.	Indicate that an app's step in a workflow failed to execute.
workflows.updateStep Update the configuration for a workflow stride.	Update the configuration for a workflow step.

Methods for classic bots

Method & Description	Clarification
api.exam Checks API calling lawmaking.	Checks API calling code.
auth.examination Checks authentication & identity.	Checks authentication & identity.
bots.info Gets information about a bot user.	Gets information about a bot user.
calls.add together Registers a new Call.	Registers a new Call.
calls.stop Ends a Phone call.	Ends a Call.
calls.info Returns information almost a Call.	Returns information almost a Phone call.
calls.participants.add Registers new participants added to a Telephone call.	Registers new participants added to a Call.
calls.participants.remove Registers participants removed from a Call.	Registers participants removed from a Phone call.
calls.update Updates information about a Call.	Updates data about a Call.

Source: https://api.slack.com/bot-users