Octov0.11.17
ReferenceConnectors

Slack

Slack messaging, events, reactions, and request verification.

The slack connector holds the bot credentials and talks to the Slack Web API; its blocks send and edit messages, add reactions, look up users, and verify and normalize inbound events. Inbound Slack events, slash commands and interactivity arrive one of two ways. Over the http connector, Slack posts them to a route you own and slack-verify-request authenticates them. In Socket Mode, the connector's own slack source holds a websocket open to Slack, so no public route or signature is involved. Either way slack-event normalizes Events API events.

slack connector

The connector provides the slack source for Socket Mode; over HTTP, inbound traffic arrives through an http source instead. The blocks that bind to it are slack-send-message, slack-update-message, slack-add-reaction, slack-lookup-user and slack-verify-request. slack-event is a pure transformer and references no connector.

Settings

SettingTypeRequiredDefaultDescription
botTokenstringYesnoneBot User OAuth token (xoxb-...) used to call the Web API.
signingSecretstringNononeVerifies inbound Slack request signatures; required to receive events over HTTP.
appTokenstringNononeApp-level token (xapp-...) with the connections:write scope; required by the slack source (Socket Mode).
timeoutdurationNo30sBounds each Slack Web API call.

An apiBaseURL setting also overrides the Web API base (default https://slack.com/api), mainly for tests; it is not exposed in the editor.

Error handling

Slack signals application errors with an ok: false response carrying an error code. Every block that calls the Web API has a failOnError setting (default true): when true a Slack error fails the flow, when false the message passes through unchanged.

slack source (Socket Mode)

Slack Socket Mode receives events, slash commands and interactivity over a websocket the runtime opens to Slack, instead of Slack posting to a public route. Turn on Socket Mode in your Slack app, generate an app-level token with the connections:write scope, and set it as the connector's appToken. No Request URL, signingSecret or slack-verify-request is involved: the connection itself is authenticated by the token.

SettingTypeRequiredDefaultDescription
ackTimeoutdurationNo2500msHow long to wait for the flow's result before acknowledging without a response payload. Slack's deadline is 3 seconds.
source:
  connector: slack
  type: slack

Each envelope Slack sends becomes one message. Its body is the same payload an HTTP flow holds after slack-verify-request, so the blocks after the source are the same either way:

vars.slackEnvelopeTypebody
events_apiThe event_callback payload; slack-event normalizes it.
slash_commandsThe command's fields: body.command, body.text, body.user_id, body.channel_id, body.response_url.
interactiveThe interaction payload, e.g. body.type, body.user.id, body.actions.

Slack requires every envelope to be acknowledged within 3 seconds:

  • An envelope that accepts a response payload (slash commands and most interactivity) is acknowledged with the flow's final body, which Slack shows as the reply, as an HTTP flow's response body would be. If the flow has not finished within ackTimeout, fails, or drops the message, the acknowledgement carries no payload and the flow keeps running.
  • Any other envelope, including every Events API event, is acknowledged as soon as it arrives, so a slow flow never makes Slack redeliver it.

The source reconnects when Slack asks it to or the connection drops. Each replica opens its own connection and Slack delivers every envelope to one of them, so scaling out needs no coordination. See samples/slack-socket-mode.yaml.

slack-verify-request block

Slack Verify Request authenticates an inbound Slack request delivered over the http connector. It verifies the HMAC-SHA256 signature over the exact request bytes using the connector's signingSecret, rejects timestamps more than 5 minutes from now (bounding replay), and aborts the flow on a bad or stale signature.

SettingTypeRequiredDefaultDescription
connectorstringYesnoneName of the slack connector to use. Its signingSecret must be set.
signatureHeaderstringNoX-Slack-SignatureVariable holding Slack's request signature.
timestampHeaderstringNoX-Slack-Request-TimestampVariable holding Slack's request timestamp.
rawBodyVarstringNorawBodyVariable holding the exact request body; must match the http source's rawBodyVar. Optional when the http source uses raw-content mode (rawBody: true), where the block reads the raw body directly and re-parses it into body.

The http source must expose the exact request bytes, either with rawBodyVar: rawBody or with rawBody: true, and copy the two signature headers into variables:

source:
  type: http
  settings:
    path: /slack/events
    headers: [X-Slack-Signature, X-Slack-Request-Timestamp]
    rawBodyVar: rawBody

In raw-content mode the block parses the verified bytes into body according to the request's content type:

RequestContent typebody after verification
Events APIapplication/jsonThe JSON payload.
Slash commandapplication/x-www-form-urlencodedThe form fields as an object: body.command, body.text, body.user_id, body.channel_id, body.response_url, body.trigger_id. A repeated field becomes a list.
Interactivity (buttons, modals, shortcuts)application/x-www-form-urlencoded with a single payload fieldThe JSON inside payload, e.g. body.type, body.user.id, body.actions.

A body that fails to parse stays the raw {contentType, rawData} envelope. Slash commands and interactivity need rawBody: true on the http source: without it the source parses every body as JSON and rejects a form post.

source:
  type: http
  settings:
    path: /slack/commands
    headers: [X-Slack-Signature, X-Slack-Request-Timestamp]
    rawBody: true

The flow's response body is Slack's immediate reply, so a slash command answers with {"response_type": "ephemeral", "text": ...} (only the caller sees it) or in_channel. Slack expects that reply within 3 seconds; slower work goes through queue-dispatch to a worker that POSTs its result to body.response_url. samples/slack-slash-command/ shows both, and the Slack bot guide walks through it.

When the payload is Slack's one-time URL-verification handshake (type: url_verification), the block sets vars.slackChallenge to true so the flow can branch, echo body.challenge back, and skip event handling.

slack-event block

Slack Event normalizes a verified Slack event_callback into a flat shape and filters it. Messages that are not an event_callback, whose event type is not in the allowlist, or that fail the filter predicate are dropped: the flow stops for them, and over HTTP that responds 204.

SettingTypeRequiredDefaultDescription
eventTypesstring[]Noallow allAllowlist of event types (e.g. app_mention, message).
filterexpressionNononeCEL predicate over the normalized body; drop the event when false.

The block replaces body with:

FieldSource
body.typeInner event type (e.g. app_mention).
body.userEvent user.
body.channelEvent channel.
body.textEvent text.
body.tsEvent ts.
body.threadTsEvent thread_ts.
body.botIdEvent bot_id, null for human messages; filter on body.botId == null to ignore the bot's own messages.
body.teamIdEnvelope team_id.
body.eventIdEnvelope event_id.
body.rawThe untouched inner event, for anything the flat fields omit.

slack-send-message block

Slack Send Message posts a message to a Slack channel or user through a slack connector (chat.postMessage). The target is a channel ID or a user ID; Slack opens a DM when given a user.

SettingTypeRequiredDefaultDescription
connectorstringYesnoneName of the slack connector to use.
targetexpressionYesnoneCEL expression for the channel ID or user ID (Slack DMs a user).
textexpressionRequired unless blocks is setnoneCEL expression for the message text.
threadTsexpressionNononeCEL expression for a parent message ts, to reply in-thread.
blocksexpressionNononeCEL expression producing Block Kit blocks (a list).
failOnErrorbooleanNotrueTurn a Slack API error into a flow error.

On success the posted message's coordinates are folded into variables so a later block can react to or update it: vars.slackChannel is the channel it was posted to, and vars.slackTs its timestamp (ts).

slack-update-message block

Slack Update Message edits a message the bot previously posted (chat.update), addressed by channel and timestamp.

SettingTypeRequiredDefaultDescription
connectorstringYesnoneName of the slack connector to use.
channelexpressionYesnoneCEL expression for the message channel ID.
timestampexpressionYesnoneCEL expression for the target message ts.
textexpressionRequired unless blocks is setnoneCEL expression for the new text.
blocksexpressionNononeCEL expression producing replacement Block Kit blocks (a list).
failOnErrorbooleanNotrueTurn a Slack API error into a flow error.

A typical pattern posts a "working…" message with slack-send-message, then updates it via vars.slackChannel and vars.slackTs.

slack-add-reaction block

Slack Add Reaction adds an emoji reaction to a message (reactions.add), typically to acknowledge an event.

SettingTypeRequiredDefaultDescription
connectorstringYesnoneName of the slack connector to use.
channelexpressionYesnoneCEL expression for the message channel ID.
timestampexpressionYesnoneCEL expression for the target message ts.
emojiexpressionYesnoneCEL expression for the reaction name without colons (e.g. white_check_mark).
failOnErrorbooleanNotrueTurn a Slack API error into a flow error.

slack-lookup-user block

Slack Lookup User resolves a Slack user into a variable, by email (users.lookupByEmail, the default) or by Slack user ID (users.info), selected with by.

SettingTypeRequiredDefaultDescription
connectorstringYesnoneName of the slack connector to use.
byenum: email | idNoemailHow to resolve the user.
emailexpressionWith by: emailnoneCEL expression for the email address to resolve.
userexpressionWith by: idnoneCEL expression for the Slack user ID to resolve (e.g. U123).
resultVarstringNoslackUserVariable to store the user object in.
failOnErrorbooleanNotrueTurn a Slack API error into a flow error.

The stored value is Slack's full user object, e.g. vars.slackUser.real_name, vars.slackUser.profile.email.

Example

Adapted from samples/slack-bot.yaml: verify events, answer the URL-verification handshake, and reply to @-mentions.

service:
  name: slack-bot

env:
  - name: SLACK_BOT_TOKEN
    required: true
  - name: SLACK_SIGNING_SECRET
    required: true

connectors:
  - name: api
    type: http
  - name: slack
    type: slack
    settings:
      botToken: ${SLACK_BOT_TOKEN}
      signingSecret: ${SLACK_SIGNING_SECRET}

flows:
  - name: slack-events
    source:
      connector: api
      type: http
      settings:
        path: /slack/events
        # Copy Slack's signature headers into vars and the exact request bytes
        # into vars.rawBody, so the signature can be verified over the raw body.
        headers: [X-Slack-Signature, X-Slack-Request-Timestamp]
        rawBodyVar: rawBody
    process:
      # 1. Authenticate the request (aborts on a bad or stale signature) and
      #    flag Slack's URL-verification handshake.
      - type: slack-verify-request
        name: verify
        settings:
          connector: slack

      # 2. Either echo the URL-verification challenge, or handle the event.
      - type: if
        name: challenge-or-event
        condition: has(vars.slackChallenge)
        then:
          process:
            - type: set-payload
              settings:
                value: '{"challenge": body.challenge}'
        else:
          process:
            # Keep only @-mentions, ignoring the bot's own messages.
            - type: slack-event
              name: mentions
              settings:
                eventTypes: [app_mention]
                filter: body.botId == null
            # Resolve the mentioning user so the reply can greet them by name.
            - type: slack-lookup-user
              name: whois
              settings:
                connector: slack
                by: id
                user: body.user
            # Reply in the same channel.
            - type: slack-send-message
              name: reply
              settings:
                connector: slack
                target: body.channel
                text: '"thanks " + vars.slackUser.real_name + ", you said: " + body.text'

Slack expects a 2xx within 3 seconds, so keep the event flow fast and offload slow work with queue-dispatch.

On this page