--- title: "Setting up a Slack Bot Connection with Unified.to" img: https://s3.us-east-2.amazonaws.com/unified-article-images/setting_up_a_slack_bot_connection_with_unified-icon.png date: 2026-06-16T14:29:00.000Z tag: Guides description: "> This guide walks you through connecting Slack Bot (slackbot) to Unified.to — including the Slack app settings you need for sending messages, interactive..." url: "https://docs.unified.to/guides/setting_up_a_slack_bot_connection_with_unified" --- # Setting up a Slack Bot Connection with Unified.to ------ _June 16, 2026_ > This guide walks you through connecting Slack Bot (slackbot) to Unified.to — including the Slack app settings you need for sending messages, interactive buttons, and receiving button-click events as Unified MessagingEvent webhooks. --- ## Overview A Slack Bot integration has three parts: | Part | Where | Purpose | | -------------------- | ------------------------ | ----------------------------------------------------------------------------- | | Slack app | api.slack.com | OAuth credentials, bot scopes, and request URLs Slack calls when events occur | | Connection | Unified dashboard | Authorizes your Slack workspace and stores the bot token | | Webhook subscription | Unified dashboard or API | Tells Unified where to deliver normalized MessagingEvent payloads | You can use Unified's shared Slack OAuth app (fastest) or register your own Slack app if you need full control over the app configuration. --- ## Important: two different URLs Slack and your application use different webhook URLs. Do not point Slack at the same URL you use as your Unified hook_url. | URL | Configured in | Receives | | ------------------------- | --------------------------------------------------------- | -------------------------------------------------------- | | Unified workspace webhook | Slack → Event Subscriptions & Interactivity → Request URL | Raw Slack Events API and interactive payloads from Slack | | Your hook_url | Unified → Webhooks → Create Webhook | Normalized Unified MessagingEvent objects | Flow: Slack → Unified workspace webhook → Unified converts the event → POST to your hook_url. Use your regional Unified API host and include your workspace ID, for example: https://api.unified.to/webhook/workspace/slackbot?workspace_id=YOUR_WORKSPACE_ID EU and AU workspaces should use the corresponding regional API host (for example api-eu.unified.to or api-au.unified.to). --- ## Step 1 — Create a Slack app 1. Go to https://api.slack.com/apps → Create New App → From scratch. 2. Name the app and select the Slack workspace you want to connect. 3. Click Create App. --- ## Step 2 — Add OAuth scopes Open OAuth & Permissions → Scopes → Bot Token Scopes and add the scopes for the objects you plan to use. Minimum for sending messages, reading history, and receiving button clicks: | Scope | Purpose | | ------------------------------------------------------------- | ------------------------------------------- | | chat:write | Send messages and messages with buttons | | channels:read / groups:read / im:read / mpim:read | List channels and DMs | | channels:history / groups:history / im:history / mpim:history | Read message history | | users:read / users:read.email / users.profile:read | Resolve message authors and button clickers | | reactions:read | Reaction events (optional) | | files:read / files:write | Attachments (optional) | > These mirror the messaging_message_write and messaging_event_read scope sets for the slackbot integration. Add additional scopes only if you use those objects. --- ## Step 3 — Set the OAuth redirect URL 1. Under OAuth & Permissions → Redirect URLs, click Add New Redirect URL. 2. Paste the Unified OAuth callback URL shown in the dashboard when you connect Slack (bot). It looks like https://api.unified.to/oauth/code (use your region's host if applicable). 3. Save URLs. --- ## Step 4 — Enable Interactivity 1. Go to Interactivity & Shortcuts and turn Interactivity ON. 2. Set Request URL to your Unified workspace webhook (not your hook_url): https://api.unified.to/webhook/workspace/slackbot?workspace_id=YOUR_WORKSPACE_ID 3. Save. Unified receives Slack block_actions payloads here, converts button clicks into MessagingEvent objects with type BUTTON_CLICK, and forwards them to your hook_url. --- ## Step 5 — (Optional) Enable Event Subscriptions Enable this if you also want message, reaction, or channel membership events (not just button clicks). 1. Go to Event Subscriptions and turn it ON. 2. Set Request URL to the same Unified workspace webhook URL as Step 4: https://api.unified.to/webhook/workspace/slackbot?workspace_id=YOUR_WORKSPACE_ID 3. Under Subscribe to bot events, add the events you need, for example message.channels, app_mention, reaction_added, member_joined_channel. 4. Save. --- ## Step 6 — Activate the integration, create a connection, and add a webhook In the Unified dashboard (or via API), complete all three steps below. 1. Go to Integrations and activate Slack (bot) for your environment. If you use your own Slack app, enter your Client ID and Client Secret. 2. Create a connection for the Slack (bot) integration and complete the OAuth flow to install the app into your Slack workspace. 3. Create a webhook on that connection with object type messaging_event and event created. Set hook_url to your application endpoint (the URL where you want to receive Unified payloads). Your hook_url is only configured on the Unified webhook subscription. Slack should always send events to the Unified workspace webhook from Steps 4–5. --- ## Receiving events When a user clicks a button or triggers a subscribed Slack event, Unified POSTs a normalized payload to your hook_url. Button clicks arrive as MessagingEvent objects with type BUTTON_CLICK — not as raw Slack block_actions JSON. See the Unified webhook documentation for payload structure, signatures, and verification. --- ## Troubleshooting | Symptom | Likely cause | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Slack URL verification fails | Request URL is missing workspace_id, uses the wrong regional host, or Unified cannot be reached from Slack | | Button clicks never reach my application | Interactivity Request URL is not set to the Unified workspace webhook, or no Unified webhook with hook_url was created | | My endpoint receives raw Slack JSON | Slack Request URL was set to your hook_url instead of the Unified workspace webhook | | invalid_auth or missing scopes | Re-install the Slack app after adding scopes (Slack requires re-consent) |