Connect Slack — Operator manual | AI Agent Builder

Connect Slack

Step by step so a client's team can talk to an agent from Slack: creating the app, scopes and events, the URL you have to build, how it answers in channels and direct messages, and what to do when it doesn't reply.

5 min read · Updated November 13, 2026

This guide connects Clínica del Sol's internal Slack to the Asistente de recepción, so staff can ask about schedules and protocols without leaving Slack. How Slack conversations are grouped —by channel, thread and person— is in the chapter Putting it in front of users.

The Slack-side steps follow Slack's console as it was when this guide was written. What the guide says about the platform side is verified against the code.

Before you start

  • One Slack app, one workspace and one agent per tenant. The tenant stores a single token and a single secret, and a Slack app has a single event URL, which points to one agent.
  • The URL decides the agent, as with Twilio: the event URL carries the agent key.
  • The tenant needs Slack enabled in its features (chapter 8).
  • Someone allowed to install apps in the clinic's Slack workspace.

The configuration is in Integrations → Slack.

1. Create the app in Slack

At api.slack.com/apps, create a new app from scratch and pick the clinic's workspace. The platform provides no manifest: the app is set up by hand.

  1. In Basic Information, copy the Signing Secret.
  2. In OAuth & Permissions, add these Bot Token Scopes:
    • chat:write, to reply;
    • app_mentions:read, to receive mentions in channels;
    • im:history, to receive direct messages.
  3. Install the app to the workspace and copy the Bot User OAuth Token, which starts with xoxb-.
  4. In App Home, turn on the Messages tab so people can send the bot direct messages.

2. Enter the credentials

In Integrations → Slack, fill in:

FieldWhat goes in
Bot TokenThe xoxb-… token from step 3
Signing SecretThe secret from step 1

Save. Both are stored encrypted. The platform does not test the token on save: if it is wrong, you only find out when the bot doesn't answer.

Slack configured: status, token and secret
Slack configured: status, token and secret

3. The event URL

The screen does not show the URL to give Slack. It is built like this:

{API URL}/webhook/slack/{tenant}/{agent}

On the Synaptic Links installation, for the clinic's reception assistant:

https://ai.synapticlinks.com.ar/api/webhook/slack/clinica-del-sol/recepcion-interna

The agent key is on the agent's detail page.

In Slack, in Event Subscriptions:

  1. Turn events on and paste the URL into Request URL. Slack verifies it right away.
  2. In Subscribe to bot events, add app_mention and message.im.
  3. Save. Slack may ask you to reinstall the app.

Slack saying "Verified" does not prove the URL is right. The platform answers the verification before looking at the tenant and the agent, so a URL with a typo also shows as verified. The real test is the next step.

Do not add message.channels. With that event and app_mention together, every mention arrives twice and the agent answers twice.

4. Test

  1. Send the bot a direct message.
  2. In a channel, invite it with /invite @app-name and mention it.

Conversations show up in Monitoring → Sessions. If the bot doesn't answer, see the table at the end.

How it behaves

  • Direct messages: it answers everything.
  • Channels: it only answers messages that contain a mention.
  • Threads: if someone writes in a thread, it answers in the thread. A standalone mention in a channel gets its answer in the channel, not in a thread.
  • One conversation per channel, thread and person. If someone else replies in the same thread, for the platform it is another conversation.
  • The agent sees the mention in the text. It receives something like <@U0ABC123> who is on duty at Sede Norte today?. Its prompt should tolerate that.
  • Formatting: bold, italics, strikethrough and links are converted to Slack's format; headings are shown in bold. Long answers are split into parts of up to 4,000 characters.
  • Text only: edited messages, files and other message types are ignored.
  • No buttons: there are no approvals or interactive options in Slack.
  • Language: it answers in the tenant's default language.

When the bot doesn't answer

The platform confirms receipt to Slack before processing the message, so Slack never shows an error: problems only end up in the server logs. Check in this order:

CheckWhy
The URL has the right tenant and agent keySlack's verification passes even with a wrong URL
The Signing Secret is this app'sIf it doesn't match, messages are discarded
The token is the current xoxb- one, with chat:writeWithout it, the agent answers but the message never goes out
app_mention and message.im are subscribedWithout events nothing arrives
In channels, the message mentions the bot and the bot is invitedWithout a mention it doesn't answer
The Messages tab is on in App HomeWithout it nobody can send it a direct message

Where it stops

  • One workspace, one app and one agent per tenant.
  • The screen does not show the event URL and offers no manifest or install button.
  • The token is not tested on save.
  • "Enabled" is informational only: to turn Slack off, delete the configuration.
  • With message.channels subscribed, any mention counts: a message mentioning someone else would also get an answer. That is why it should not be subscribed.
  • No buttons, files or "typing" indicator.
  • Protection against repeated events is per server: with several instances, a Slack retry could be answered twice.

To check

  • The app has the chat:write, app_mentions:read and im:history scopes.
  • The event URL ends in the right agent's key.
  • The subscribed events are app_mention and message.im, without message.channels.
  • A direct message and a channel mention both get answers and show up in Sessions.
  • To turn Slack off, the configuration is deleted; the status alone is not enough.