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.
- In Basic Information, copy the Signing Secret.
- 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.
- Install the app to the workspace and copy the Bot User OAuth Token, which starts with
xoxb-. - 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:
| Field | What goes in |
|---|---|
| Bot Token | The xoxb-… token from step 3 |
| Signing Secret | The 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.

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:
- Turn events on and paste the URL into Request URL. Slack verifies it right away.
- In Subscribe to bot events, add
app_mentionandmessage.im. - 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
- Send the bot a direct message.
- In a channel, invite it with
/invite @app-nameand 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:
| Check | Why |
|---|---|
| The URL has the right tenant and agent key | Slack's verification passes even with a wrong URL |
| The Signing Secret is this app's | If it doesn't match, messages are discarded |
The token is the current xoxb- one, with chat:write | Without it, the agent answers but the message never goes out |
app_mention and message.im are subscribed | Without events nothing arrives |
| In channels, the message mentions the bot and the bot is invited | Without a mention it doesn't answer |
| The Messages tab is on in App Home | Without 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.channelssubscribed, 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:readandim:historyscopes. - The event URL ends in the right agent's key.
- The subscribed events are
app_mentionandmessage.im, withoutmessage.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.