Asking from Slack

Once your admin sets it up, you can ask your agents from Slack. Send the SkillTree bot a direct message, or mention it in a channel it is in, and it answers in a thread under your message.

Asking a question

• Direct message: open the SkillTree app in Slack and type your question. Every message you send starts its own thread.
• In a channel: mention the bot, such as @SkillTree what did we agree with Acme?. The bot needs to be in the channel first: type /invite @SkillTree there.

While it works, the bot puts an hourglass on your message and posts “Thinking…” in the thread. The answer replaces that message. A long answer arrives as a few messages in a row.

The Company Brain answers unless you name a department. Start with the department’s name and a colon, or with “ask” and the name:

• sales: how did last week go?
• ask finance what we spent on travel in May

The name can be the department’s name or its agent’s name. If it does not match a department you may use, the Company Brain answers the whole message as you wrote it.

Follow-ups

Reply in the bot’s thread to keep going. The bot remembers what was said earlier in that thread. In a direct message you can just reply in the thread; in a channel, mention the bot again in your reply. A new message outside the thread starts a fresh conversation.

A thread stays with the agent it started with.

Who it answers, and what they see

The bot answers only people with a SkillTree account. It finds you by the email address on your Slack profile, so that address must be the one you sign in to SkillTree with. Anyone else gets a short reply asking them to ask an admin for an invite. If your account exists but you have never signed in, the bot asks you to sign in once first.

You see exactly what you would see in the app: your departments, your own connected apps and the company’s shared knowledge, under your allowance and your organization’s credits. While the organization has no plan or too few credits the bot says so instead of answering, and an answer that runs out of credits partway ends with that reason.

Private sources stay private. When you ask in a channel and the answer uses something only you can see, such as your own email, the bot sends the answer to you by direct message and says so in the thread. It never posts it where others can read it.

Sources, files and approvals

• Sources appear as numbered links after the answer, like they do in the app. A link to one of your company’s files opens it in SkillTree.
• Files the brain makes, such as an image or a PDF, are listed by name with a link to the chat in SkillTree, where you download them.
• Writes such as a Gmail draft, a Google Doc or a Notion page are never made from Slack. The bot says an approval is waiting, with a link to the chat in SkillTree. Approve or decline it there, as in Approving writes. When you decide, the bot finishes its answer in the Slack thread.

In the app

Every Slack conversation also shows in your chat list in SkillTree. Its title is the word Slack followed by your first question, so you can tell it apart and carry on there.

Turning it on (admin only)

Under Settings, on the Integrations tab, the Slack Front Door section has the workspace’s Slack app secrets (the signing secret and the bot token, entered there and stored encrypted), the switch, and a checklist with the workspace’s own events address to paste into Slack. The switch can be on before Slack is ready; the bot starts answering once everything on the list is in place. Turning it off stops all answers at once, and removing the secrets makes the events address stop answering.

For the deploying team

The front door uses its own settings and does not need the Slack connector (CONNECTOR_SLACK_ENABLED). One Slack app can serve both. Each workspace brings its own Slack app, and its secrets are entered in that workspace’s Settings, never in the deployment’s environment (SLACK_SIGNING_SECRET and SLACK_BOT_TOKEN are refused at startup). Slack only sends events to an https address, so the deployment must be reachable at an https APP_PUBLIC_URL.

1. Under Settings → Integrations, copy the workspace’s events URL from the Slack Front Door section; it ends in the workspace’s id.
2. At api.slack.com/apps choose Create New App, then From a manifest, pick the company’s Slack workspace and paste the manifest below, with the request_url replaced by that events URL.
3. Under Basic Information, copy the Signing Secret. Choose Install to Workspace and approve, then under OAuth & Permissions copy the Bot User OAuth Token (it starts with xoxb-). Paste both into the Slack Front Door section and save; they are stored encrypted and never shown again.
4. Open Event Subscriptions in the Slack app and choose Retry beside the Request URL so Slack checks it again. It shows Verified once the workspace answers, and the section names the Slack workspace after its first event.
5. Switch the front door on under Settings → Integrations.

display_information:
  name: SkillTree
  description: Ask your company's agents from Slack.
features:
  app_home:
    home_tab_enabled: false
    messages_tab_enabled: true
    messages_tab_read_only_enabled: false
  bot_user:
    display_name: SkillTree
    always_online: true
oauth_config:
  redirect_urls:
    - https://YOUR-SKILLTREE-ADDRESS/connections/slack/callback
  scopes:
    bot:
      - app_mentions:read
      - chat:write
      - im:history
      - im:read
      - im:write
      - users:read
      - users:read.email
      - reactions:write
      - channels:read
      - channels:history
      - groups:read
      - groups:history
      - team:read
settings:
  event_subscriptions:
    request_url: https://YOUR-SKILLTREE-ADDRESS/api/slack/events/YOUR-WORKSPACE-ID
    bot_events:
      - app_mention
      - message.im
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false

The first eight bot scopes are what the front door needs: reading mentions and direct messages, posting and updating its answers, the hourglass reaction, opening a direct message for private answers, and looking people up by email. The last five, and the redirect URL, are only for the Slack connector; leave them in if you also use it, so one app covers both. To offer personal Slack connections as well, add the user scopes listed on the Slack page. Leave token rotation off.

Slack expects each event to be acknowledged within three seconds. The deployment acknowledges straight away and answers in the background, checks every request’s signature and refuses one older than five minutes, and ignores Slack’s retries of an event it already received. SLACK_FRONT_DOOR_MAX_CONCURRENT (4 by default) sets how many questions one API replica answers at once. See Environment variables.