{"id":21180691,"url":"https://github.com/hexastack/hexabot-channel-slack","last_synced_at":"2026-05-15T18:07:40.518Z","repository":{"id":258023451,"uuid":"870225014","full_name":"Hexastack/hexabot-channel-slack","owner":"Hexastack","description":"The Slack Channel Extension for Hexabot Chatbot / Agent Builder","archived":false,"fork":false,"pushed_at":"2026-05-04T08:33:22.000Z","size":498,"stargazers_count":2,"open_issues_count":4,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-04T09:13:27.276Z","etag":null,"topics":["agent","artificial-intelligence","chatbot","chatbot-framework","large-language-model","large-language-models","llm","slack","slack-bot","slackbot"],"latest_commit_sha":null,"homepage":"https://docs.hexabot.ai","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Hexastack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-10-09T16:54:57.000Z","updated_at":"2026-05-04T08:33:27.000Z","dependencies_parsed_at":"2024-12-16T11:24:18.242Z","dependency_job_id":"6c88ad7b-6e79-4547-a510-7d68fe223e31","html_url":"https://github.com/Hexastack/hexabot-channel-slack","commit_stats":null,"previous_names":["hexastack/hexabot-channel-slack"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/Hexastack/hexabot-channel-slack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hexastack%2Fhexabot-channel-slack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hexastack%2Fhexabot-channel-slack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hexastack%2Fhexabot-channel-slack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hexastack%2Fhexabot-channel-slack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Hexastack","download_url":"https://codeload.github.com/Hexastack/hexabot-channel-slack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hexastack%2Fhexabot-channel-slack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33074445,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T11:35:32.926Z","status":"ssl_error","status_checked_at":"2026-05-15T11:35:31.362Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","artificial-intelligence","chatbot","chatbot-framework","large-language-model","large-language-models","llm","slack","slack-bot","slackbot"],"created_at":"2024-11-20T17:45:52.770Z","updated_at":"2026-05-15T18:07:40.511Z","avatar_url":"https://github.com/Hexastack.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hexabot Slack Channel Extension\n\n`hexabot-channel-slack` adds Slack Events API, Interactivity, App Home, and Web\nAPI support to Hexabot v3. It is a first-class v3 channel extension discovered\nby `@hexabot-ai/api` and registered with the channel name `slack`.\n\n[Hexabot](https://hexabot.ai/) is an open-source chatbot and agent builder for\nmulti-channel, multilingual conversational automation. Learn more in the\n[Hexabot repository](https://github.com/Hexastack/Hexabot).\n\n## Features\n\n- Native Hexabot v3 `HttpChannelHandler` implementation.\n- Slack request signing with `x-slack-signature`, `x-slack-request-timestamp`,\n  `req.rawBody`, HMAC-SHA256, five-minute replay protection, and timing-safe\n  comparison.\n- Slack URL verification responses using the plaintext `challenge` expected by\n  Slack.\n- Events API support for direct messages, app mentions, file shares, and App\n  Home opens.\n- Interactivity support for Block Kit button postbacks.\n- App Home publishing with custom Block Kit content and Hexabot menu actions.\n- Subscriber identity based on Slack user IDs, with profile lookup through\n  `users.info`.\n- Authenticated private Slack file downloads for inbound attachments.\n- Outbound text, quick replies, buttons, URL buttons, lists, carousels, and file\n  uploads.\n- Optional auto-join and retry for public channels when Slack returns\n  `not_in_channel`.\n- Optional non-DM thread replies using Slack `thread_ts`.\n\n## Installation\n\nInstall the package in the same workspace or deployment that runs\n`@hexabot-ai/api`:\n\n```sh\nnpm add hexabot-channel-slack\n```\n\nRestart the Hexabot API after installation. The channel appears with the name\n`slack`.\n\nFor local development inside this package:\n\n```sh\nnpm install\nnpm test\nnpm run typecheck\nnpm run build\n```\n\n## Package Interface\n\n- Package name: `hexabot-channel-slack`\n- Channel name: `slack`\n- Main package entry: `dist/index.js`\n- Channel discovery entry: `dist/index.channel.js`\n- Source webhook endpoint: `https://\u003cyour-domain\u003e/api/webhook/\u003csourceId\u003e`\n\n## Prerequisites\n\nBefore configuring the channel, make sure you have:\n\n- a Slack workspace;\n- admin access to create and configure Slack apps in that workspace;\n- a public HTTPS URL for the Hexabot API. For local testing, expose the API with\n  a tunnel such as ngrok;\n- a Hexabot v3 project running with this extension installed;\n- Hexabot credentials created for the Slack bot token and signing secret.\n\nThis extension uses Slack HTTP Events and Interactivity. Socket Mode and OAuth\ninstallation flows are intentionally out of scope for this release.\n\n## Slack App Setup\n\nYou can create the Slack app from scratch or from a manifest. Both approaches\nproduce the same configuration.\n\n### Option 1: Create App From Scratch\n\n1. Open [Slack API Apps](https://api.slack.com/apps).\n2. Click **Create New App**.\n3. Choose **From scratch**.\n4. Enter an app name and select the Slack workspace where it will be installed.\n5. Open **Basic Information** and copy the **App ID** and **Signing Secret**.\n6. Store the signing secret as a Hexabot credential.\n\n### Option 2: Create App From Manifest\n\n1. Open [Slack API Apps](https://api.slack.com/apps).\n2. Click **Create New App**.\n3. Choose **From an app manifest**.\n4. Select the target workspace.\n5. Paste a manifest similar to this one, replacing the placeholder URL and app\n   name:\n\n```yaml\ndisplay_information:\n  name: Hexabot\nfeatures:\n  app_home:\n    home_tab_enabled: true\n    messages_tab_enabled: false\n  bot_user:\n    display_name: Hexabot\n    always_online: false\noauth_config:\n  scopes:\n    bot:\n      - app_mentions:read\n      - chat:write\n      - im:history\n      - im:write\n      - users:read\n      - files:read\n      - files:write\n      - channels:read\n      - channels:join\nsettings:\n  event_subscriptions:\n    request_url: https://\u003cyour-domain\u003e/api/webhook/\u003csourceId\u003e\n    bot_events:\n      - app_mention\n      - message.im\n      - app_home_opened\n  interactivity:\n    is_enabled: true\n    request_url: https://\u003cyour-domain\u003e/api/webhook/\u003csourceId\u003e\n  org_deploy_enabled: false\n  socket_mode_enabled: false\n  token_rotation_enabled: false\n```\n\n6. Create the app, then open **Basic Information** to copy the App ID and\n   Signing Secret.\n\n## OAuth Scopes\n\nOpen **OAuth \u0026 Permissions** and add these bot token scopes:\n\n| Scope | Purpose |\n| --- | --- |\n| `app_mentions:read` | Read messages where the bot is mentioned. |\n| `chat:write` | Send Slack messages. |\n| `im:history` | Receive direct-message events. |\n| `im:write` | Open/resume direct messages for App Home interactions. |\n| `users:read` | Read Slack user profile data. |\n| `files:read` | Download files shared with the bot. |\n| `files:write` | Upload files from Hexabot to Slack. |\n| `channels:read` | Read public channel metadata. |\n| `channels:join` | Join public channels before retrying sends. |\n\nAfter changing scopes, reinstall the app to the workspace.\n\n## Events API Configuration\n\nOpen **Event Subscriptions** in the Slack app settings:\n\n1. Enable events.\n2. Set **Request URL** to:\n\n```txt\nhttps://\u003cyour-domain\u003e/api/webhook/\u003csourceId\u003e\n```\n\n3. Subscribe to these **Bot Events**:\n\n- `app_mention`\n- `message.im`\n- `app_home_opened`\n\n4. Save changes.\n\nSlack verifies the URL by sending a `url_verification` request. The Hexabot\nsource must already have the correct signing secret credential configured so the\nextension can verify the request before returning the challenge.\n\n## Interactivity Configuration\n\nOpen **Interactivity \u0026 Shortcuts** in the Slack app settings:\n\n1. Enable interactivity.\n2. Set **Request URL** to the same v3 source endpoint:\n\n```txt\nhttps://\u003cyour-domain\u003e/api/webhook/\u003csourceId\u003e\n```\n\n3. Save changes.\n\nThe extension currently handles Block Kit button actions. URL-only buttons are\nignored because Slack opens the URL directly.\n\n## App Home Configuration\n\nOpen **App Home** in the Slack app settings:\n\n1. Enable the **Home Tab**.\n2. Disable the **Messages Tab** unless your product flow needs it separately.\n3. Save changes.\n\nWhen a user opens App Home, Hexabot publishes:\n\n- the custom Block Kit array from `home_tab_content`;\n- Hexabot menu entries as Slack sections and buttons.\n\nApp Home opens do not emit chatbot message events.\n\n## Install the Slack App\n\nOpen **Install App** in the Slack app settings:\n\n1. Click **Install to Workspace**.\n2. Authorize the requested scopes.\n3. Copy the **Bot User OAuth Token** from **OAuth \u0026 Permissions**.\n4. Store the bot token as a Hexabot credential.\n\n## Hexabot Source Configuration\n\nCreate one Hexabot source for each Slack app/workspace pair.\n\nRequired settings:\n\n- `bot_token`: credential containing the Slack Bot User OAuth Token.\n- `signing_secret`: credential containing the Slack signing secret.\n- `app_id`: Slack App ID. Events for other apps are ignored.\n\nOptional settings:\n\n- `team_id`: Slack workspace/team ID. When set, events for other workspaces are\n  ignored.\n- `home_tab_content`: JSON array of Slack Block Kit blocks rendered before the\n  Hexabot menu in App Home.\n- `enable_home_tab`: publish App Home content when a user opens the Home tab.\n  Defaults to `true`.\n- `reply_in_threads`: reply in the source Slack thread for non-DM\n  conversations when thread metadata exists. Defaults to `true`.\n- `auto_join_public_channels`: call `conversations.join` and retry once when\n  Slack returns `not_in_channel` for a public channel. Defaults to `true`.\n- `thread_inactivity_hours`: controls Hexabot v3 thread rollover. Defaults to\n  `24`.\n\nSave the source before verifying the Slack Events URL.\n\n## Supported Inbound Messages\n\n- Direct-message text from `message.im` becomes a Hexabot text event.\n- App mentions from `app_mention` become text events after Slack bot mentions\n  are stripped.\n- Slack file shares with private download URLs become attachment events.\n- Messages containing both text and files are split into one text event and one\n  attachment event.\n- Block Kit non-URL button clicks become postback events.\n- App Home button clicks without a channel open/resume a DM through\n  `conversations.open` before the postback is emitted.\n- Bot messages, self-authored bot messages, unsupported message subtypes,\n  URL-only buttons, wrong app IDs, and wrong team IDs are ignored.\n\nSubscriber identity uses the Slack user ID as `senderForeignId`. Channel\nattributes include:\n\n- `teamId`\n- `enterpriseId`\n- `appId`\n- `conversationId`\n- `conversationType`\n- `userId`\n- `messageTs`\n- `threadTs`\n\n## Supported Outbound Messages\n\n- Text messages are sent with `chat.postMessage`.\n- Quick replies and postback buttons are sent as Block Kit `section` and\n  `actions` blocks.\n- URL buttons are sent as Slack URL buttons.\n- Lists are sent as stacked `section` and `actions` blocks, capped to Slack\n  message block limits.\n- Oversized paginated lists reserve an action for `VIEW_MORE`.\n- Carousels are sent as Slack carousel blocks capped at 10 cards.\n- Attachments are sent with `filesUploadV2`.\n- Quick replies after an attachment are sent as a follow-up Block Kit message.\n\n## File Handling\n\nInbound Slack files are private. The extension downloads them with:\n\n```txt\nAuthorization: Bearer \u003cbot_token\u003e\n```\n\nOutbound attachment messages upload Hexabot attachments through Slack\n`filesUploadV2`. When the attachment reference is a URL, the extension downloads\nthe URL first and then uploads the resulting stream to Slack.\n\n## Security Notes\n\nEvery Slack POST request is verified before decoding:\n\n1. `x-slack-signature` must be present.\n2. `x-slack-request-timestamp` must be present and no older than five minutes.\n3. `req.rawBody` must be available.\n4. The extension computes `v0:{timestamp}:{rawBody}` with HMAC-SHA256 and the\n   source signing secret.\n5. The computed digest is compared with Slack's digest using `timingSafeEqual`.\n\nEnsure the Hexabot API keeps `req.rawBody` available for webhook routes.\n\n## Troubleshooting\n\nSlack URL verification fails:\n\n- confirm the source has the correct signing secret credential;\n- confirm the public URL reaches the Hexabot API route;\n- confirm your reverse proxy does not strip Slack signature headers;\n- confirm raw body capture is enabled.\n\nMessages are not received:\n\n- confirm the app is installed in the workspace;\n- confirm `app_mention`, `message.im`, and `app_home_opened` are subscribed;\n- for channel messages, invite the bot to the channel and mention it;\n- direct messages require `im:history`.\n\nMessages are not sent:\n\n- confirm `chat:write` is granted and the app was reinstalled after scope\n  changes;\n- for public channels, keep `channels:join` and\n  `auto_join_public_channels=true` or invite the bot manually;\n- check Slack API errors in Hexabot logs.\n\nFiles are not downloaded or uploaded:\n\n- confirm `files:read` and `files:write` are granted;\n- confirm the bot can access the conversation where the file was shared;\n- for outbound URL attachments, confirm the URL is reachable by the Hexabot API.\n\n## Development\n\nCommon commands:\n\n```sh\nnpm test\nnpm run typecheck\nnpm run build\nnpm run build:publish\nnpm pack --dry-run\n```\n\n`build:publish` removes generated output, builds `dist`, and verifies that the\npackage export files exist.\n\n## Publishing\n\nThe package keeps the v2 release workflow commands:\n\n```sh\nnpm run release:patch\nnpm run release:minor\n```\n\nBoth commands create an npm version commit and tag, then push `main` with tags.\nThe GitHub Actions release workflow builds, tests, packs, and publishes the\npackage to npm when the tagged package version is not already published.\n\nRequired repository secret:\n\n- `NPM_TOKEN`: npm automation token with publish access for\n  `hexabot-channel-slack`.\n\n## Limitations\n\n- Socket Mode is not implemented.\n- OAuth installation flow is not implemented.\n- Public-channel general history is not subscribed. Channel conversations are\n  intentionally processed through `app_mention`.\n- One source maps to one Slack app/workspace. Use multiple sources for multiple\n  workspaces.\n\n## Contributing\n\nContributions are welcome. Please read\n[How to contribute to Hexabot](https://github.com/Hexastack/Hexabot/blob/main/CONTRIBUTING.md)\nbefore submitting changes.\n\n[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](https://github.com/Hexastack/Hexabot/blob/main/CODE_OF_CONDUCT.md)\n\nJoin the Hexabot community on [Discord](https://discord.gg/rNb9t2MFkG).\n\n## License\n\nThis software is licensed under the Fair Core License, FCL-1.0-ALv2. Full terms\nare available in [LICENSE.md](./LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhexastack%2Fhexabot-channel-slack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhexastack%2Fhexabot-channel-slack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhexastack%2Fhexabot-channel-slack/lists"}