Skip to main content

Slack

This library allows using Slack with Wing.

Prerequisites​

Supported Features​

  • Events
  • Direct Channel Messages

Unsupported Features (TODO)​

  • Distribution Management
  • Interactive Components
  • Slash Commands
  • Workflows
  • Incoming Webhooks

Installation​

Use npm to install this library:

npm i @winglibs/slack

Bring it​

bring slack;
bring cloud;

let myBotToken = new cloud.Secret(name: "mybot_token");

let slackbot = new slack.App(token: myBotToken);

/// When registering events, the inflight function will be called with the context and event
/// The `ctx` is a reference to the context of the event, and provides client methods to interact with channels, threads, etc..
/// The `event` is the raw Json event data from Slack and can be used to extract information from the event
slackbot.onEvent("app_mention", inflight (ctx, event) => {
  let message = new slack.Message();
  message.addSection({
    fields: [
      {
        type: slack.FieldType.mrkdwn,
        text: "*Wow this is markdown!!*\ncool beans!!!"
      }
    ]
  });

  ctx.channel.postMessage(message);
});

Create your Slack App​

  1. Go to the Slack API Dashboard and create a new app.
  2. Select Create from Scratch.
  3. For the README example above, ensure you provide the following permissions:
  • app_mentions:read
  • chat:write
  • chat:write.public
  • channels:read
  1. Navigate to Events and subscribe to the following events:
  • app_mention
  1. Navigate to OAuth & Permissions and install the app to your workspace
  2. Copy the Bot User OAuth Token to your clipboard
  3. Navigate to Event Subscriptions and enable events, then subscribe to bot events:
  • app_mention

Running in the Wing Simulator​

First lets configure our Slack bot token as a secret in the simulator.

wing secrets

When prompted, paste the Bot User OAuth Token you copied earlier.

Next when running in the Wing Simulator, you will need to expose the endpoint of the Slackbot API, this can be done through the simulator console by selecting Open tunnel for this endpoint

Take this URL and navigate back to your Slack App, under the Event Subscriptions section, paste the URL into the Request URL field and append /slack/events to the end of the URL.

Running in AWS​

First lets configure our Slack bot token as a secret in AWS.

wing secrets -t tf-aws

When prompted, paste the Bot User OAuth Token you copied earlier.

Next, let's run the following command to deploy our app to AWS.

wing compile -t tf-aws
terraform -chdir=target/main.tfaws init
terraform -chdir=target/main.tfaws apply

After compiling and deploying your app using tf-aws you there will be an endpoint called Slack_Request_Url that is part of the terraform output. The URL should end with /slack/events. It will look something like this:

Apply complete! Resources: 11 added, 0 changed, 0 destroyed.

Outputs:

App_Api_Endpoint_Url_E233F0E8 = "https://zgl8r8wsng.execute-api.us-east-1.amazonaws.com/prod"
App_Slack_Request_Url_FF26641D = "https://zgl8r8wsng.execute-api.us-east-1.amazonaws.com/prod/slack/events"

Navigate back to your Slack App, under the Event Subscriptions section, paste the URL into the Request URL field and append /slack/events to the end of the URL.

Post Directly to a Channel​

If you want to post directly to a channel, you can do so by using the following code:

let postMessage = new cloud.Function(inflight () => {
  let channel = bot.channel("NAME|ID");
  channel.post("hello world!");
});

Finding a Channel ID​

If you prefer to use a channel ID over a channel name, you can find the channel ID by right-clicking on the channel name and select View channel details. The channel ID will be at the bottom of the popup modal.​

API Reference​

Table of Contents​

SlackUtils (preflight class) ​

No description

Constructor​

new(): SlackUtils

Properties​

No properties

Methods​

SignatureDescription
static inflight post(body: Json, token: str): JsonNo description

Message (inflight class) ​

Represents a Message block see: https://api.slack.com/block-kit

Constructor​

new(): Message

Properties​

NameTypeDescription
sectionsMutArray
No description

Methods​

SignatureDescription
inflight addSection(section: Section): voidNo description
inflight toJson(): JsonReturns Json representation of message

App (preflight class) ​

No description

Constructor​

new(props: AppProps): App

Properties​

NameTypeDescription
apiApiNo description

Methods​

SignatureDescription
inflight channel(id: str): ChannelRetrieve a channel object from a channel Id or name
onEvent(eventName: str, handler: inflight (EventContext, Json): Json?): voidRegister an event handler (for available events see: https://api.slack.com/events)

Channel (inflight class) ​

Represents the context of a slack channel

Constructor​

new(): Channel

Properties​

NameTypeDescription
idstrThe channel id

Methods​

SignatureDescription
inflight post(message: str): JsonPost raw text to a channel
inflight postMessage(message: Message): JsonPost a message block to a channel

EventContext (inflight class) ​

Represents the context of an event callback

Constructor​

new(): EventContext

Properties​

NameTypeDescription
channelChannelNo description
threadThreadNo description

Methods​

No methods

EventContext_Mock (inflight class) ​

Internally used for mocking event context

Constructor​

new(): EventContext_Mock

Properties​

NameTypeDescription
channelChannelNo description
threadThreadNo description

Methods​

No methods

MockChannel (inflight class) ​

Only used for internal testing

Constructor​

new(): MockChannel

Properties​

NameTypeDescription
idstrThe channel id

Methods​

SignatureDescription
inflight post(message: str): JsonPost raw text to a channel
inflight postMessage(message: Message): JsonPost a message block to a channel

Thread (inflight class) ​

Represents the context of a slack thread

Constructor​

new(): Thread

Properties​

NameTypeDescription
channelChannelThe channel context
timestampstrThe thread timestamp

Methods​

SignatureDescription
inflight post(message: str): JsonPost raw text to a thread
inflight postMessage(message: Message): JsonPost a message to a thread

IThread (interface) ​

The bahvioral interface of a thread

Properties​

No properties

Methods​

SignatureDescription
inflight post(message: str): JsonNo description
inflight postMessage(message: Message): JsonNo description

Block (struct) ​

No description

Properties​

NameTypeDescription
fields
Array
No description
typeBlockTypeNo description

Field (struct) ​

No description

Properties​

NameTypeDescription
textstrNo description
typeFieldTypeNo description

Section (struct) ​

No description

Properties​

NameTypeDescription
fields
Array
No description

AppProps (struct) ​

Properties for Slack bot

Properties​

NameTypeDescription
ignoreBotsbool?Whether events from bot users should be ignored (default: true)
tokenSecretThe token secret to use for the app

CallbackEvent (struct) ​

No description

Properties​

NameTypeDescription
app_idstr?No description
bot_idstr?No description
channelstrNo description
event_tsstrNo description
teamstr?No description
tsstrNo description
typestrNo description
userstrNo description

MessageCallbackEvent (struct) ​

No description

Properties​

NameTypeDescription
app_idstr?No description
bot_idstr?No description
channelstrNo description
event_tsstrNo description
teamstr?No description
textstrNo description
tsstrNo description
typestrNo description
userstrNo description

SlackEvent (struct) ​

No description

Properties​

NameTypeDescription
typestrNo description

VerificationEvent (struct) ​

No description

Properties​

NameTypeDescription
challengestrNo description
tokenstrNo description
typestrNo description

BlockType (enum) ​

No description

Values​

NameDescription
sectionNo description

FieldType (enum) ​

No description

Values​

NameDescription
plain_textNo description
mrkdwnNo description