Slack

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 arrive over the http connector, since Slack posts JSON to a route you own, and the slack-verify-request and slack-event blocks process that request.

slack connector

The connector provides no source; inbound events arrive through an http source. 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

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-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.

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

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.

The block replaces body with:

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.

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.

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.

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.

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'