Skip to main content

Slack Integration

Connect your Slack workspace to Phoenix so OttoBot can respond to your team's messages in the correct workspace under your organization's tenant.

Prerequisites​

Before you begin, ensure you have:

  • A Slack workspace where you have permission to install apps
  • Admin access to your Phoenix organization's Integrations settings

Create the Slack App​

Phoenix uses OttoBot's published Slack app manifest, which configures all required permissions and Socket Mode automatically. Creating the app from this manifest is the recommended approach — you do not need to hand-pick scopes.

1. Open the Slack app creation page:

Go to https://api.slack.com/apps and click Create New App.

2. Choose "From a manifest":

Select From a manifest in the dialog that appears.

3. Select your workspace:

Choose the Slack workspace where you want OttoBot to operate, then click Next.

4. Paste the OttoBot manifest:

Copy the contents of the OttoBot Slack app manifest and paste it into the YAML editor. Click Next, review the summary, then click Create.

note

The manifest is the authoritative source for required scopes and Socket Mode configuration. Do not modify the manifest — paste it as-is.

Obtain Your Tokens​

Bot User OAuth Token (xoxb-…)​

After the app is created:

  1. In the left sidebar, go to OAuth & Permissions.
  2. Under OAuth Tokens for Your Workspace, click Install to Workspace.
  3. Review the requested permissions and click Allow.
  4. Copy the Bot User OAuth Token — it starts with xoxb-.

App-Level Token (xapp-…)​

  1. In the left sidebar, go to Basic Information.
  2. Scroll down to App-Level Tokens and click Generate Token and Scopes.
  3. Give the token a name (e.g., socket-mode).
  4. Click Add Scope and select connections:write.
  5. Click Generate and copy the token — it starts with xapp-.

Configure in Phoenix​

  1. In Phoenix, navigate to Integrations in your organization's settings.
  2. Find Slack and click Connect.
  3. Enter your tokens in the two fields:
FieldValue
Bot User OAuth TokenThe xoxb-… token from OAuth & Permissions
App-Level TokenThe xapp-… token from Basic Information → App-Level Tokens
  1. Click Configure Integration.

The tokens are stored encrypted at rest. They are never returned to the browser in plaintext.

Rotating Tokens​

If you need to rotate your tokens:

  1. Go back to https://api.slack.com/apps and open your OttoBot app.
  2. Generate new tokens using the steps above.
  3. In Phoenix, open the Slack integration and click Edit to enter the new tokens.

The shared-mt OttoBot pod detects the rotation on its next poll via the updated timestamp and refreshes the Socket Mode connection automatically.

Disconnecting​

To remove the Slack integration for your organization, open the Slack integration in Phoenix and click Remove. The OttoBot pod will stop serving your workspace on its next refresh cycle.

Troubleshooting​

SymptomLikely causeSolution
"Bot User OAuth Token must start with xoxb-"Wrong token pasted in the Bot Token fieldEnsure you copy the Bot User OAuth Token from OAuth & Permissions, not the app token
"App-Level Token must start with xapp-"Wrong token in the App Token fieldEnsure you copy the App-Level Token from Basic Information → App-Level Tokens
OttoBot not responding in SlackApp not installed to workspace, or Socket Mode not enabledConfirm you clicked Install to Workspace in step 3 of Obtain Your Tokens; also verify the manifest was pasted unmodified (socket_mode_enabled: true must be present)
Integration shows connected but OttoBot is offlineToken expired or revokedRotate both tokens (see Rotating Tokens)

Next Steps​