Slack Integration

OttoBot answers questions about accounts, products and market signals in Slack, using HG Insights data. You create a Slack app for your workspace from the manifest HG Insights provides, then give HG Insights the app's two tokens. OttoBot then answers in DMs and in channels you invite it to.

Before you start

Confirm with HG Insights that your organization is activated for OttoBot. If you skip this check, the app installs normally but never answers.

You need:

• a Slack workspace admin (or someone allowed to install apps in your workspace), and
• an owner or admin of your organization in HG Insights, to enter the tokens.

Questions at any step: customersupport@hginsights.com.

1. Create the Slack app from the manifest

1. Open the Slack App Manifest page and copy the YAML.
2. Go to api.slack.com/apps and select Create New App → From a manifest.
3. Pick the workspace where OttoBot will work, then select Next.
4. Paste the YAML unchanged, select Next, review the summary, then select Create.

Don't remove scopes, events or settings from the manifest. An edited manifest usually installs without complaint and then fails in ways that are hard to trace (see If something goes wrong).

Permissions you're approving

Read this before you select Install to Workspace in the next step: that's where Slack asks a workspace admin to approve these. Every permission comes from the manifest. "Not used today" means OttoBot currently makes no call that needs it. It stays because the manifest is installed as published, and editing it is unsupported.

Bot scopes

Scope	Why OttoBot has it
app_mentions:read	Receive messages that @mention OttoBot in channels
channels:history	Receive messages in public channels it's a member of, so it can follow up in a thread it already answered in
groups:history	The same, for private channels it's been added to
im:history	Receive your direct messages to OttoBot
chat:write	Post and update its replies
reactions:write	Add the 👀 reaction that shows it has seen your message
files:read	Read a file you attach to a message for OttoBot, so it can use it in its answer: plain-text UTF-8 files (.txt, .md, .csv, .json, .html) and .pdf, .docx, .pptx and .xlsx documents, up to 10 MiB each and 10 per message. Older Office formats (.doc, .ppt, .xls), images and password-protected Office files are declined
files:write	Upload files OttoBot produces for you into the conversation
users:read	Look up the Slack profile of the person asking
users:read.email	Read that person's email address, so OttoBot can recognize who is asking and personalize its answers. Without it, Slack returns profiles with no email
assistant:write	Added by Slack automatically when the agent experience (below) is on. Declared so the manifest matches what Slack provisions
channels:read, groups:read, im:read, im:write	Basic information about channels and DMs. Not used today
reactions:read	Read reactions. Not used today

Events

Event	Why
app_mention	Delivers @mentions of OttoBot
message.channels, message.groups	Deliver channel messages, so OttoBot can follow a thread it's already part of. It ignores everything else
message.im	Delivers your DMs to OttoBot
app_home_opened, app_context_changed	Required by Slack's agent experience. OttoBot doesn't act on them

Settings

Setting	Why it must stay as-is
socket_mode_enabled: true	OttoBot connects out to Slack. Without Socket Mode it never receives anything
features.agent_view	Turns a DM with OttoBot into an assistant thread, which is what shows the live status line while it works
interactivity off	OttoBot uses no buttons or forms
token_rotation_enabled: false	HG Insights stores long-lived tokens. Rotation would expire them and take OttoBot offline

2. Install the app and copy the two tokens

OttoBot needs two different tokens from two different screens. They're easy to swap.

Bot User OAuth Token (starts with xoxb-)

1. In your new app, open OAuth & Permissions.
2. Under OAuth Tokens, select Install to Workspace and approve the permissions listed in Permissions you're approving.
3. Copy the Bot User OAuth Token.

App-Level Token (starts with xapp-)

1. Open Basic Information and scroll to App-Level Tokens.
2. Select Generate Token and Scopes, name it (for example socket-mode), and add the scope connections:write.
3. Select Generate and copy the token.

3. Enter the tokens in HG Insights

1. In HG Insights, open your organization's Integrations page.

2. On the Slack card, select Configure.

3. Fill in the two fields:

   Field	Paste
   Bot User OAuth Token	the xoxb-… token from OAuth & Permissions
   App-Level Token	the xapp-… token from Basic Information → App-Level Tokens

4. Select Configure Integration.

The tokens are stored encrypted and are never shown back to you. OttoBot picks up a new or changed token within a few minutes, with no restart.

4. Verify it works

1. In Slack, find OttoBot under Apps and open its Messages tab.
2. Send it a question, for example: What CRM does Acme Corporation use?
3. OttoBot adds a 👀 reaction, then replies with an answer drawn from HG Insights data. While it looks something up, a status line under the message box shows what it's doing. The status line appears only in DMs, and only while OttoBot is using a tool; a quick answer may not show one.

Optional, in a channel: invite OttoBot (/invite @OttoBot), then @mention it with a question. It replies in a thread, and you can keep asking in that thread without mentioning it again. If it stops replying in an older thread, @mention it again. Channel replies never show the status line; that's expected.

• DMs work by default in Slack.
• Group DMs (a DM with OttoBot and other people) are not served. OttoBot ignores ordinary messages sent there.

If something goes wrong

What you see	Cause	What to do
Saving the tokens fails with "Slack credentials must include a botToken starting with xoxb- and an appToken starting with xapp-. phoenixApiKey is optional, but when present it must be a non-empty string — omit the key entirely rather than sending an empty value." (Ignore the phoenixApiKey part; you don't supply one.)	The tokens are swapped, or one was copied from the wrong screen	Paste the xoxb- token from OAuth & Permissions into Bot User OAuth Token, and the xapp- token from Basic Information → App-Level Tokens into App-Level Token
OttoBot never answers anything, DM or @mention	Your organization isn't activated yet, the app wasn't installed (Install to Workspace), or Socket Mode is off	Confirm activation with HG Insights. In the app settings, check that Socket Mode is on and that the app is installed. If you edited the manifest, see the next row
Some things work and others don't (for example DMs work but channel threads don't, or answers aren't personalized)	The manifest was edited and a scope or event is missing	Open the app at api.slack.com → App Manifest, replace it with the YAML from the Slack App Manifest page, save, then Install App → Reinstall to Workspace. If reinstalling issues a new xoxb- token, update it in HG Insights
OttoBot worked before and has gone silent	A token was revoked or regenerated, or the app was uninstalled	Reinstall the app if needed, copy both current tokens, then on the Slack card select Update and save them
In a DM, OttoBot answers questions that need a lookup but never shows a status line	The app has no agent experience (features.agent_view), typically because it was created from an older manifest. (No status line in a channel, or on a quick answer that uses no tool, is expected, not this problem.)	Replace the app's manifest with the current YAML (it includes agent_view), save, and Reinstall to Workspace. Adding the assistant:write scope alone doesn't turn it on
OttoBot replies "DMs aren't enabled for your organization. Please @-mention me in a channel instead."	DMs have been turned off for your organization (they're on by default)	@mention OttoBot in a channel, or ask HG Insights to turn DMs back on
OttoBot's reply includes "I don't have permission to read files in this workspace. Ask a Slack workspace admin to reinstall the OttoBot app so it gets the files:read permission."	Your app was installed before OttoBot could read attachments, so it lacks files:read	Open the app at api.slack.com → App Manifest, replace it with the current YAML from the Slack App Manifest page, save, then Install App → Reinstall to Workspace. If that issues a new xoxb- token, update it in HG Insights
No reply in a group DM	Group DMs aren't served. OttoBot ignores ordinary messages there without replying	DM OttoBot one-to-one, or @mention it in a channel it's been invited to

Disconnecting

To stop using OttoBot in Slack:

1. In HG Insights, on the Slack card, select Remove. OttoBot stops serving your workspace within a few minutes.
2. Optionally, delete the app at api.slack.com/apps.

Next Steps

• Microsoft Teams Integration: use OttoBot in Teams as well
• Supported MCP Clients: connect HG Insights to other AI tools
• MCP Tool Documentation: the full tool catalog