Slack Bot access

Slack follows the bring-your-own-app (BYO) mode: the workspace administrator creates a Slack app, installs it in his own Slack workspace, and then pastes its token into Multica. Each agent has its own Slack app - so multiple agents can each have an independent, individually @bot in the same Slack workspace. (This is different from Lark. Lark’s binding is a scan-code installation process.)

The entire setup process is below and takes about five minutes. Finally you will get two tokens to paste into Multica:

• a Bot token - starting with xoxb-
• an App-level token - starting with xapp-

1. Open https://api.slack.com/apps and click Create New App.
2. Select From a manifest.
3. Select the Slack workspace where you want to install the app.
4. Switch to the YAML tab, paste the following manifest, check it again, and then create the app.

display_information:
  name: Multica
features:
  app_home:
    home_tab_enabled: false
    messages_tab_enabled: true
    messages_tab_read_only_enabled: false
  bot_user:
    display_name: Multica
    always_online: true
oauth_config:
  scopes:
    bot:
      - app_mentions:read
      - channels:history
      - groups:history
      -im:history
      - mpim:history
      - chat:write
      - users:read
settings:
  event_subscriptions:
    bot_events:
      -app_mention
      - message.im
      - message.channels
      - message.groups
      - message.mpim
  interactivity:
    is_enabled: false
  org_deploy_enabled: false
  socket_mode_enabled: true
  token_rotation_enabled: false

This manifest already has everything Multica needs configured, so you don’t have to set anything up manually:

Configuration items	Why you need it
app_home.messages_tab_enabled: true	Enables members to open the bot and privately message it. Without it, the bot cannot be directly messaged.
bot_user	Create the Bot identity used by @ and post replies.
chat:write	Send the agent's reply back to Slack.
app_mentions:read + app_mention event	Receive @mentions in a channel.
im:history + message.im	Receive private messages sent to Bot (each private message will be read).
channels:history / groups:history / mpim:history + corresponding message.* event	Receive messages from public channels, private channels and group private chats. In these scenarios, the bot only responds to messages that have been sent to it.
socket_mode_enabled: true	Bot connects to the outside through Socket Mode - No need for any public URL / request URL.
interactivity.is_enabled: false	Multica's prompts are pure links, not buttons, so interactivity is not required.

There is no OAuth redirect URL here because BYO does not use OAuth.

Want to use a specific name in Slack? Change display_information.name and features.bot_user.display_name (e.g. to your agent's name) before creating, or edit them later in App Home. Slack displays Bots by their bot display name, which can be different from the app name.

2. Install app and copy Bot token

1. In the left navigation of the app, open Install App (or OAuth & Permissions).
2. Click Install to Workspace and approve.
3. Copy the Bot User OAuth Token - it starts with xoxb-. This is your Bot token.

3. Create App-level token

App-level token is used to authorize Socket Mode connections. It can only be created in the console (it is not part of OAuth).

1. Open Basic Information → App-Level Tokens and click Generate Token and Scopes.
2. Give it a random name.
3. Click Add Scope and select connections:write from the list (this is a selector - select it, don't type by hand).
4. Click Generate and copy the token - it starts with xapp-. This is your App-level token.

4. Connect it in Multica

1. Open the agent in Agents → Your Agent → Integrations tab (or the Integrations block in the left column).
2. Click Connect Slack.
3. Paste the Bot token (xoxb-) and App-level token (xapp-) and click Connect.
4. The agent displays Connected to Slack. The bot is now listening via its own Socket Mode connection.> These two tokens must come from the same Slack app, and that app corresponds to exactly one agent. Connecting to an app that is already connected to another agent or workspace will be denied. To move an app to another agent, disconnect it first; reconnecting an agent with a new app will update that agent's Bot in place.

Do you want to do this set of settings for multiple agents? Each agent goes through the entire process - each agent has its own Slack app and its own pair of tokens, and they will be displayed as independent Bots in your Slack workspace.

Entrance	Behavior
Agent → Integrations	Connect Slack will be visible to owners and administrators; when connected it will turn into a Connected to Slack logo with a Disconnect action.
Private Chat Bot	Workspace members send messages directly to the Bot. This conversation will become a Multica chat session for the agent; every private message will be read.
@ it in the channel	Invite the Bot in (/invite @your-bot) and then @ it. Only the message @ it will be read - the bot will not listen to the entire channel. Each @bot's thread is its own session.
/issue Command	A message starting with /issue <title> (the text can be attached in the following lines) will create a new Multica issue in the workspace under your name.
Reply	The agent's reply will be sent back to the same private chat or thread.

The first time you @ or privately message the Bot, it will reply with a Bind your account prompt. Click the link, log in to Multica, and your Slack identity will be bound to your Multica membership - it's this step that allows the agent to act as you (for example, /issue will record the issue in your name). This link is one-time use and expires in about 15 minutes; send a message to the Bot to get a new one.

Only workspace members can use the bot. If you are not a member, or have skipped identity binding, the bot will not run - your messages will be discarded (recorded for audit purposes only, message content is not saved).

Conversations with /issue

• In Channel - Bots will not join automatically. Run once /invite @your-bot, then @your-bot <your message>. You have to @ it again every time you ask (Bot only reads @ its message).
• In Private Chat - Open the Bot from the Apps section of the Slack sidebar and message it directly; no @ is required.
• Create issue - Send /issue Fix the login redirect; add a few lines after the title to describe it.

• Connected bots Lists each Bot in the workspace and its respective bound agents (visible to all members).
• Disconnect Owner/Administrator only. This will cause the bot to stop receiving Slack messages and tear down its connection; a record of the installation will be retained for auditing purposes, and you can reconnect later.

• Connect/Disconnect requires workspace Owner or Administrator.
• Conversation with Bot requires you to be a member of the workspace and have bound your Slack identity. The rest were thrown away.
• For discarded messages, the message content is never saved - only a discard reason is recorded for auditing purposes.

When self-deploying, Slack is turned off until you set up the static encryption key. This key will encrypt each app’s bot token + app-level token before it is stored in the database. BYO does not require an OAuth client id/secret, nor does it require a deployment-level app token - each installation uses the pair of tokens pasted in by the administrator.

1. Generate a 32-byte key and set it to the API server:

   MULTICA_SLACK_SECRET_KEY=<base64-encoded 32-byte key>
   

   For example: openssl rand -base64 32.

2. Restart the API. Until the key is set, Settings → Integrations will display a "Slack integration not enabled" prompt, and the Connect Slack entry will remain hidden.

The key must decode exactly 32 bytes - openssl rand -base64 32 will do it. Think of it as a long-lived key: rotating or losing it renders stored tokens unable to be decrypted, forcing each bot to reconnect. The "Bind your account" link is spelled out with your web application address (MULTICA_APP_URL, which falls back to FRONTEND_ORIGIN when not set) - this value is already present in normal deployment and does not require additional configuration.

• Chat Integration - How the channel engine, sessions and authorization work
• Agents · Chat · Issues
• Environment Variables - Complete self-deployment configuration reference