Slack - 18F/charlie GitHub Wiki

Charlie developer documentation > Slack

The Slack utility provides helper methods to make it easier to post messages to Slack beyond the simpler forms provided by Bolt.

NOTE: Many of the methods have configuration options, such as providing a Slack client or token. These primarily exist for testing. Bots should not need to set these optional arguments as they will be configured when Charlie starts up.

A note on types used on this page:

Message refers to a message object created by your bot that will be sent to Slack. These are far beyond the scope of this document, but they are covered extensively in Slack's message composition documentation.

SlackMessage refers to a message object provided by Bolt. These are used to derive information necessary to execute functions, such as responding or reacting to the message.

SlackClient refers to a Slack HTTP API object, which is accessible from the client property on the object passed into Bolt event handlers. When Charlie starts up, it preconfigures the Slack utility to use the client populated by Bolt, so bots generally shouldn't need to set it.

SlackUser refers to a user object as returned from the Slack HTTP API.

function addEmojiReaction(SlackMessage msg, String reaction) : Promise

Adds a reaction to an existing Slack message

Argument Description
msg A message object from Slack that the reaction should be attached to
reaction The emoji string of the reaction to attach, in the form :emoji:

Returns

  • A promise that resolves with the message returned by Slack, or rejects if there is an error. See the Slack API documentation for more information on what may be resolved.

function getChannelID(String channelName, { SLACK_TOKEN: String } options }) : Promise<String>

Some Slack features require referring to a channel by its ID, but bots may not know the channel's ID up front. Rather than figuring out the ID and making it part of Charlie's configuration, this function allows bots to fetch a channel's ID dynamically at runtime.

Argument Description
channelName The channel name to fetch the ID for. Most bots should not set this
options An object used to inject configuration data.

Default: process.env
options.SLACK_TOKEN The Slack token used to authenticate to the web API.

Default: process.env.SLACK_TOKEN

Returns

  • A promise that resolves the channel ID for the given name, or undefined if the channel name is not found (either because it does not exist or it is a private channel that Charlie is not in). The promise rejects on error.

    Channel IDs are cached in memory indefinitely. Once a channel name is mapped to an ID, this function will always return the cached result. There is an edge case where a channel name might change its ID while Charlie is running, but that seems unlikely enough not to worry about it.

function getSlackUsers({ SLACK_TOKEN: String } options}) : Promise<[SlackUser]>

Get a list of all Slack users in Charlie's workspace (gsa-tts). This function does not filter the users in any way. However, it does cache results for 24 hours.

Argument Description
options An object used to inject configuration data. Most bots should not set this.

Default: process.env
options.SLACK_TOKEN The Slack token used to authenticate to the web API.

Default: process.env.SLACK_TOKEN

Returns

  • A promise that resolves a list of all Slack users. See the Slack API documentation for more information about user objects. The promise rejects on error.

function getSlackUsersInConversation({ client: SlackClient, event: { channel: String }} options) : Promise<[SlackUser]>

Get a list of users who are in a channel, direct message, or group DM. This function has a weird prototype relative to the others and probably ought to be refactored to more closely align with the rest. It only takes one argument and it is required. However, the options.client property is not only optional, but it should not be set by most bots. Only the options.event.channel property is actually required.

Argument Description
options An object used to inject configuration data. Part of this object is required.
options.client A SlackClient object. Most bots should not set this.

Default: the web client provided by Bolt
options.event A SlackMessage event object, or a plain object containing a channel property. Required.
options.event.channel A channel/conversation ID. Slack waffles on the language;. Channels are a subset of conversations. Conversations also include direct messages and group DMs. This function technically works with conversations, but channels are conversations so it works.

Returns

  • A promise that resolves a list of Slack users in the specified channel, DM, or group DM. See the Slack API documentation for more information about user objects. The promise rejects on error.

function postEphemeralMessage(Message msg, { SLACK_TOKEN: String } options) : Promise

Post an ephemeral message in Slack. Ephemeral messages are those that show up in a channel, only a single user can see, and go away after a while. This function allows a bot to create an ephemeral message that is not necessarily in response to a user SlackMessage. For responding to a user's message, consider the postEphemeralResponse function instead.

Arguments Description
msg A Slack message object. See the Slack message composition documentation for more information about this object. NOTE: Unlike most Message objects, this one must include a user property set to the Slack ID of the user who should see the ephemeral message.
options An object used to inject configuration data. Most bots should not set this.

Default: process.env
options.SLACK_TOKEN The Slack token used to authenticate to the web API.

Default: process.env.SLACK_TOKEN

Returns

  • A promise that resolves on success or rejects on error.

function postEphemeralResponse(SlackMessage toMsg, Message msg, { SLACK_TOKEN: String } options) : Promise

Post an ephemeral message in response to a message in Slack. Ephemeral messages are those that show up in a channel, only a single user can see, and go away after a while.

Arguments Description
toMsg A SlackMessage to respond to.
msg A message object. See the Slack message composition documentation for more information about this object. NOTE: This object does not need to set user, channel, or thread_ts properties as they will all be overridden based on the values in toMsg.
options An object used to inject configuration data. Most bots should not set this.

Default: process.env
options.SLACK_TOKEN The Slack token used to authenticate to the web API.

Default: process.env.SLACK_TOKEN

Returns

  • A promise that resolves on success or rejects on error.

function postMessage(Message message, { SLACK_TOKEN: String } options) : Promise

Post a message into a Slack channel.

Arguments Description
message A message object. See the Slack message composition documentation for more information about this object.
options An object used to inject configuration data. Most bots should not set this.

Default: process.env
options.SLACK_TOKEN The Slack token used to authenticate to the web API.

Default: process.env.SLACK_TOKEN
  • A promise that resolves with the message returned by Slack, or rejects if there is an error. See the Slack API documentation for more information on what may be resolved.

function sendDirectMessage(String|[String] to, Message message, { SLACK_TOKEN: String } options) : Promise

Post a direct message to one or more users. Note that sending to more than one user will open a group DM. If you want to send DMs individually to multiple users, call this function separately for each user.

Arguments Description
to A user ID to send to a single user, or an array of user IDs to send to a group DM.
message A message object. See the Slack message composition documentation for more information about this object.
options An object used to inject configuration data. Most bots should not set this.

Default: process.env
options.SLACK_TOKEN The Slack token used to authenticate to the web API.

Default: process.env.SLACK_TOKEN

Returns

  • A promise that resolves if the direct message could be created. Rejects otherwise. Note that this resolution does not tell you whether the message successfully posted, making it considerably different from the postMessage function.

function setClient(SlackClient client)

Sets the default Slack web client to use for HTTP API calls when the client is not overridden by the caller. Bots should not need to call this function. It is called by Charlie during initialization and is set to the authenticated API client created by Bolt.

Arguments Description
client A Bolt web API client object.

Charlie developer documentation

⚠️ **GitHub.com Fallback** ⚠️