Event Metadata

A sample _metadata for an incoming event will be similar to the following object:

The Slack integration provides you with a Manifest that allows you to setup most of the heavy Slack App configuration in seconds. To get started, simply click on the link provided here:

Simply follow the on-screen instructions until the app is installed to your workspace. You will be required to allow the app to perform the necessary actions - you must be a workspace admin to do that.

You will still need to perform a few actions to correctly setup your app. First, visit the App Manifest menu. It may have an orange warning box at the top: in that case, click the "Click here to verify" link to make that warning disappear. Another way to perform this verification if needed is by visiting Event Subscriptions and performing the same operation.

Next, visit the OAuth & Permissions menu, copy the Bot User Token and save it for later.

Next, select App Home in the left-side menu. Enter a Display Name and a Default Name for your bot and select Always Show My Bot as Online.

At the bottom of the same App Home page, under Show Tabs, make sure the Messages Tab toggle is on and the Allow users to send Slash commands and messages from the messages tab checkbox is checked.

Next, visit Basic Information from the left-side menu, copy the App ID, Client ID, Client Secret and Signing Secret under App Credentials and save them for later.

On the same page, you can also customize the appearance of your chatbot in Slack (image, colors...).

Finally, back in CSML Studio, paste the credentials you retrieved earlier: Bot User Token, App ID, Client ID, Client Secret, Signing Secret, then click on Submit.

You should now be able to see your app in the left sidebar of your Slack workspace, under Apps. This is where you can chat with your slack bot!

Text

Slack has partial markdown support in text components.

say "His palms are sweaty, knees weak, arms are heavy"
say Text("There's vomit on his sweater already, mom's spaghetti")
say "He's _nervous_, but **on the surface** he looks ~calm and ready~"

Typing, Wait

In Slack, Wait and Typing have the same behavior. No typing indicator exists in slack, so the bot will simply wait for the duration given (in milliseconds) before the next message is processed.

say Typing(1000)
say Wait(1000)

Question, Button

Slack makes it possible to style your buttons and define a custom payload that is sent to the chatbot on click. Available styles are "danger" and "primary". Slacks recommends to only use primary on one button in a list, and danger even less often.

say Question(
  "Hi! My name is:",
  buttons=[
    Button("What?", payload="btn1"),
    Button("Who?", payload="btn2", style="danger"),
    Button("Slim Shady", payload="btn3", style="primary"),
  ]
)
hold
say "User selected: {{event}}"

CSML Studio will also take advantage of Slack's features to update the content of the component when an option is chosen, so that the user's choice appears clearly after they select an option.

Image

Send the URL of an image. Slack will attempt to display it.

say Image(
  "http://placekitten.com/500/500",
  title="Nice kitten", // optional
  alt="this is a photo of a cute kitten", // optional
)

Video, Audio, Url

Generic files will render as standard URLs. When it can, Slack will try to display the URL nicely, such as the Wikipedia link below.

say Video("https://cdn.csml.dev/customers/93bfb0df-fb6b-4ed2-87b0-8d93a09b0ad8/files/cbaa0959-fe58-4a2a-89c3-c414a1f38748/big_buck_bunny.mp4")
say Audio("https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3")
say Url("https://www.wikipedia.org/")

Carousel, Card

A Carousel is essentially a collection of Card elements A single Card will display as a Carousel of 1 element.

do card1 = Card(
  "The Marshall Mathers LP",
  subtitle="Release date: May 23, 2000",
  image_url="https://upload.wikimedia.org/wikipedia/en/a/ae/The_Marshall_Mathers_LP.jpg",
  buttons=[
    Button("Listen to this album", payload="marshallmatherslp1"),
    Url("https://www.eminem.com/", text="Visit eminem.com"),
  ]
)
do card2 = Card(
  "The Slim Shady LP",
  subtitle="Release date: February 23, 1999",
  image_url="https://upload.wikimedia.org/wikipedia/en/3/35/Eminem_-_The_Slim_Shady_LP_CD_cover.jpg",
  buttons=[
    Button("Listen to this album", payload="theslimshadylp"),
    Url("https://www.eminem.com/", text="Visit eminem.com"),
  ]
)
do card3 = Card(
  "The Marshall Mathers LP 2",
  subtitle="Release date: November 5, 2013",
  image_url="https://upload.wikimedia.org/wikipedia/en/8/87/The_Marshall_Mathers_LP_2.png",
  buttons=[
    Button("Listen to this album", payload="marshallmatherslp2"),
    Url("https://www.eminem.com/", text="Visit eminem.com"),
  ]
)

say Carousel(cards=[card1, card2, card3])

You can add several Button or Url buttons to your Card components.

Input, Textarea

// the same works with Textarea()
say Input(
  title="Enter something below",
  description="This is a simple text field, and you can say whatever you want",
  placeholder="Whatever you want",
  submit_label="Submit",
)

Radio, Dropdown

// the same works with Dropdown()
say Radio(
  // Mandatory
  options = [
    Button("Cats 🐕", payload="meow"),
    Button("Dogs 🐶", payload="woof"),
    Button("Hot dogs 🌭", payload="yummy"),
  ],

  // Optional fields:
  title="What's your favorite animal?",
  description="You can only pick one!",
)

Multiselect, Checkbox

// the same works with Multiselect()
say Checkbox(
  // Mandatory
  options = [
    Button("Cats 🐕", payload="meow"),
    Button("Dogs 🐶", payload="woof"),
    Button("Hot dogs 🌭", payload="yummy"),
  ],

  // Optional fields:
  title="What's your favorite animal?",
  description="You can pick many!",
)

Calendar

say Calendar(title="Select your date of birth", submit_label="OK")

Full reference

For a complete reference of all the code presented on this page, refer to the following gist:

Event Metadata

A sample _metadata for an incoming event will be similar to the following object:

{
  "_channel": {
    "app_id": "YYYYYYYYY",
    "type": "slack",
    "name": "Slack channel"
  },
  "last_name": "Doe",
  "user_id": "XXXXXXXX",
  "email": "john.doe@example.com",
  "first_name": "John"
}

CSML Studio supports Slack as one of its channels. Slack is a very popular option at startups and schools, and is widely used as a "ChatOps" solution by tech teams.