Guides›Slack Adapter Starter Guide

Slack Adapter Starter Guide

Last updated 2026-02-12

Reference implementation:

  • rooaak-slack-adapter-starter

What Rooaak developers deploy

Deploy the Slack starter service, then wire:

  1. Slack events -> starter /webhooks/slack/events
  2. Rooaak message.responded webhook -> starter /webhooks/rooaak

Required env

  • ROOAAK_API_KEY
  • ROOAAK_WEBHOOK_SECRET
  • ROOAAK_AGENT_ID
  • SLACK_SIGNING_SECRET
  • SLACK_BOT_TOKEN

Slack app configuration

  1. Slack app -> Event Subscriptions -> enable events.
  2. Request URL: https://<your-host>/webhooks/slack/events
  3. Subscribe bot events: app_mention (minimum), plus channel message events if needed.
  4. OAuth scopes: app_mentions:read, chat:write
  5. Reinstall app after scope/event changes.
  6. Invite bot user to target channel(s).

Rooaak webhook registration

bash
curl -X POST https://www.rooaak.com/api/v1/webhooks \
  -H "Authorization: Bearer $ROOAAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://<your-host>/webhooks/rooaak",
    "events": ["message.responded"]
  }'

Persist returned secret as ROOAAK_WEBHOOK_SECRET.

Session mapping

  • sessionId: slack:<channel_id>:<thread_ts_or_ts>
  • metadata.channel.type: slack
  • include provider IDs in metadata.channel.*

Smoke test

  1. In Slack channel with bot invited, send:
    • @<bot-name> reply with exactly slack-smoke-ok
  2. Verify bot posts response in channel/thread.

Failure checks

  1. 401 invalid slack signature:
    • verify SLACK_SIGNING_SECRET matches Slack app secret.
  2. Event received but no reply:
    • verify bot has chat:write, app reinstalled, and channel membership.