Chat apps (Microsoft Teams and Slack)

Enterprise feature (new in 1.19.4, helpdesk). See the Helpdesk overview.

Many people would rather ask for help where they already are. Connect Microsoft Teams or Slack and they can message the CompassDocs app to raise a request, get the desk’s replies in the same chat and answer there, and decide approvals from a card. A mention in a channel you choose can open a ticket for that channel’s team.

There is no store listing: you register your own Azure Bot or Slack app and paste its credentials into CompassDocs. The steps are below and on the settings page.

Connecting an app

Desk settings → Chat apps (“Let people raise and follow requests, and approve them, from Microsoft Teams or Slack.”). It needs the desk capability Helpdesk settings (Admins, out of the box).

The page has a card for each app. Connect opens the card’s form: the credentials, the address to paste into your bot or app (with Copy), and How to set up Teams or How to set up Slack, the steps below.

• Secrets are stored encrypted and never shown again. A saved secret shows as dots with Replace. Leave it alone and the saved one is kept.
• Saving calls nobody. Connect (or Save) only stores what you typed. Test checks it with Microsoft or Slack and shows the answer under the card (“Last test Nov 7: …”).
• Disconnect (“Disconnect Microsoft Teams?”) stops reading and sending that app’s messages at once, and forgets who is who there. Tickets raised from the app stay, and replies to them go by email.

A connected card says Connected, with “Connected · tenant 1a2b3c4d…” for Teams or “Connected · Acme” for Slack, and who connected it and when.

Microsoft Teams

The Microsoft Teams card takes:

• App ID: the Microsoft App ID of your Azure Bot, a GUID like 00000000-0000-0000-0000-000000000000.
• Client secret: the secret’s Value, from Certificates & secrets. A new app ID needs the secret again (“Paste the client secret again: a saved secret is only used with the app ID it was saved for.”).
• Tenant ID: your Microsoft Entra tenant ID, as a GUID (Microsoft Entra admin center, Overview). A domain such as contoso.onmicrosoft.com is refused: “Enter the tenant ID, a GUID like 00000000-0000-0000-0000-000000000000 (Microsoft Entra admin center, Overview), not a domain.” Messages from any other tenant are refused.

The Messaging endpoint to paste into the bot is https://<your-domain>/api/helpdesk/chat/teams/messages.

To set it up:

1. In the Azure portal, create an Azure Bot of type Single Tenant in your tenant. Copy its Microsoft App ID, and under Certificates & secrets add a client secret (copy its Value).
2. In the bot’s Configuration, paste the messaging endpoint. Under Channels, add Microsoft Teams.
3. In the Teams Developer Portal, make an app with this bot in the Personal and Team scopes, and two message actions with “Fetch a dynamic set of parameters”:
   • Get help, command ID getHelp;
   • Turn into a ticket, command ID makeTicket.
4. Publish it to your organisation and install it for the people who should use it (Teams admin centre, setup policies).
5. Paste the app ID, client secret and tenant ID into the card, Connect, then Test.

Test asks Microsoft for a bot token with the app ID, secret and tenant, and reads the Bot Framework’s signing keys. It answers “Microsoft accepted the app ID and secret, and Teams’ signing keys can be read.” or says what’s wrong.

People in Teams are matched through the Microsoft 365 directory sync, which must be on (see Who is who).

Slack

The Slack card takes:

• Bot token: the Bot User OAuth Token (xoxb-…) from OAuth & Permissions.
• Signing secret: from the app’s Basic Information page.

The Request URL (Events and Interactivity) is one address for both: https://<your-domain>/api/helpdesk/chat/slack/events.

To set it up:

1. At api.slack.com/apps, create an app From an app manifest. Open How to set up Slack on the card and choose Copy app manifest: the Request URL is already in it.
2. Install it to your workspace.
3. Paste the bot token and the signing secret into the card, Connect, then Test.

The manifest sets everything the app needs:

Bot scopes	app_mentions:read, channels:history, chat:write, commands, im:history, im:write, reactions:read, users:read, users:read.email
Bot events	app_mention, message.im, reaction_added
Interactivity	On, with the same Request URL
Message shortcuts	Get help (cd_get_help, “Raise a request about this message”) and Turn into a ticket (cd_make_ticket, “Agents only. Open a ticket from this message”)
App home	The Messages tab, so people can message the app

Test checks the token with Slack and compares the token’s scopes with the list above. It answers “Connected to Acme.” or, for example, “Connected to Acme, but the app is missing users:read.email. Add the scopes, then reinstall the app.” The workspace Slack names is pinned (by Test, or by the first signed event if you never test), and events from any other workspace are refused.

What people can do

Once an app is connected, What people can do in Teams (or in Slack) holds four switches:

Switch	Default	What it allows
Raise a request	On	“Message the CompassDocs app, or use the Get help message action on any message.”
Follow and reply	On	“Replies from the desk arrive in the chat; their answers go back to the ticket.”
Approve and decline	On	“Approvers get a card with Approve and Decline. Their own click decides, like the email buttons.”
Turn a channel message into a ticket	Off	“Agents only, from the message’s menu.”

The switches and the channels below are saved together with Save chat app settings.

Who is who

Every message is matched to a CompassDocs account before anything happens. The account must be active and hold Get help.

• Teams: the person’s Microsoft Entra object ID is looked up in the directory that the Microsoft 365 directory sync keeps, and then the one active account linked to that directory entry. The sync must be on, and each account linked to its entry.
• Slack: the email address on the person’s Slack profile, which Slack must call confirmed, has to be the confirmed address of exactly one CompassDocs account: not typed in by the person on their own profile, and not shared with another account. This is the same rule as devices in Get help. Slack is asked again whenever someone raises a request, decides an approval or opens a channel ticket, and a remembered link is re-checked after a day. Someone whose Slack address now belongs to another account is forgotten, together with their direct chats.

Someone who can’t be matched gets a polite answer and no ticket: “I couldn’t find your CompassDocs account, so I can’t raise requests for you yet. Ask IT to add you (with the same email address you use here), then message me again.” An account without Get help is told “Your CompassDocs account can’t raise helpdesk requests. Ask IT if you need to.”

Raising a request

Someone messages the app directly, or uses Get help on any message (the message action in Teams, the message shortcut in Slack).

1. The app suggests a request type and up to two articles: “That sounds like a Laptop or device problem for IT Service Desk. These might help first: • …”. The type is the one of the person’s own request types whose words best match the message. Only types whose form has no required question are offered; anything that needs a form is raised in Get help.
2. A Raise a request? card follows, with the type and team, the Device (from their assets, when an asset source is connected) and What’s wrong. Raise request raises it as it stands; Edit lets them change the type, the device and the text.
3. “Done: #1047. I’ll message you here when IT Service Desk replies.”

A request raised from chat goes through the same intake as Get help: request types, routing rules, workflows and notifications. Its subject is the message’s first line (up to 120 characters). A request raised with Get help on another message links back to it (“From a message in Teams”).

• A card works for an hour: “That card has expired. Send your message again and I’ll start a new one.”
• Clicking twice raises one ticket: “Already raised: #1047.”
• “hi”, “hello”, “help” or “?” on their own get “What do you need help with? Describe it in a sentence or two.”
• Get help on a message needs a direct chat with the app already: “Open a chat with the CompassDocs app first, then try again.” Installing the app for everyone (Teams setup policies) gives each person one.

Following and replying

While Follow and reply is on:

• A public reply from the desk reaches the requester’s direct chat with the app: “Ana Kowalski (IT Service Desk) replied on #1047:”, the text (up to 2,500 characters), how many files it has, and Open #1047. It also goes by email and the bell as your notification policy says. In Slack it is threaded under the “Done” line.
• Never sent to chat: internal notes, and a newbie’s reply while it waits for review or after it is returned. Nothing is sent about a ticket in the recycle bin or an anonymised one.
• The requester’s answer becomes their message on the ticket, as in Get help. A message counts as an answer when it is:
  • a reply in the request’s own Slack thread;
  • written as “#1047 …”;
  • or a plain message within 3 days of the last message about an open request. Then the app says “Added to #1047. Something else? Say new request.”
• “new request”, “new”, “start over” or “cancel” starts afresh.
• A reply to a closed request isn’t added: “#1047 is closed, so I didn’t add that to it. Send it again to raise a new request.”

Only replies go to chat. Notices such as “solved” and “approval decided” still go by email and the bell.

Approvals

While Approve and decline is on, an approver who uses the app gets an Approval needed card for each request waiting on them: who asks for what, the request’s answers, and Approve, Decline…, Ask a question and Open.

• Only the approver’s own click decides. The click is decided as the clicking person’s own account, by the same rules as deciding in Get help or from the email. Anyone else is told “Only Ana Kowalski can decide this.” (up to two names, then “or another approver”). The person is looked up afresh before every decision.
• Decline… asks for the reason (“Say why you’re declining: the requester sees your note.”). Ask a question asks for the question, which lands on the request as the approver’s public message and notifies the requester as the web does.
• After a decision, the card is replaced: Approved or Declined, “You approved #1047 for Daniel in Teams.”, with the note when declined.

Who gets a card:

• Teams: only people whose personal chat with the app is known: they messaged it, or it was installed for them. Installing the app for everyone covers this.
• Slack: the approver is found by their confirmed address, and a direct message is opened.

Channels that open tickets

Channels that open tickets lists the channels where a message can become a ticket. Add a channel asks for:

• App: Teams or Slack.
• Channel ID: a Slack ID starts with C (open the channel’s details: the ID is at the bottom). A Teams ID starts with 19: (Get link to channel: it’s the part after /channel/).
• Name: shown in the table, such as it-help.
• Team: the desk team its tickets go to.
• Opened by: A mention (“Any message that mentions @CompassDocs”) or, in Slack only, A reaction with its name, such as ticket (“The :ticket: reaction”).

Invite the app to the channel first (in Teams, add the app to that team).

Teams opens channel tickets only from a mention, because Teams doesn’t give apps the message someone reacted to. A reaction trigger for a Teams channel is refused.

When the trigger fires, the message becomes a ticket for the channel’s team, with the person who posted it as the requester (if they can be matched), and a link back to the message. The thread gets “Opened #1047 for IT Service Desk. Daniel will hear from the desk in a direct message.”

• Desk replies go to the requester’s direct chat, never into the channel, so a reply is never posted publicly.
• One ticket per message, however many people react or mention the app: “That message is already #1047.”
• A mention in a channel that isn’t listed gets “This channel doesn’t open tickets. Message me directly to raise a request.”
• An unknown poster gets the “ask IT to add you” answer, and no ticket.

You can list up to 50 channels.

Turn into a ticket (agents)

With Turn a channel message into a ticket on, an agent can use Turn into a ticket on any channel message. The poster becomes the requester, and the ticket goes to the channel’s team when the channel is listed, or to the agent’s own team when they work exactly one. The ticket gets an internal line: “Ana opened this from a message in #it-help (Slack).”

Only agents can use it: “Only helpdesk agents can turn a message into a ticket. Use Get help to raise your own request.” With the switch off: “Turning messages into tickets is off for this app. An admin can turn it on in Desk settings, Chat apps.”

Security

• Every request is checked before it is read. Anything that fails gets 401 and is never processed.
  • Teams: the Bot Framework token (RS256), with signing keys from Microsoft’s published metadata, the issuer, the audience (your app ID), the expiry with five minutes of leeway, and the service address in the token matching the message’s. The message’s tenant must be your tenant ID; a message with no tenant is refused.
  • Slack: the signature over the request with your signing secret, the timestamp within five minutes, compared in constant time, and the pinned workspace.
• A disconnected app reads nothing and sends nothing. Its endpoint answers 401.
• Answers come at once. CompassDocs answers each request straight away (Slack wants an answer within three seconds) and does the work after. A retried event is recognised and handled once.
• Outbound calls go only to Microsoft and Slack. Every call to them goes through the server’s address checks to their own hosts, and redirects are never followed.
• A new app ID, tenant or Slack workspace, or a disconnect, forgets that app’s links: who is who, the chats tickets live in, and the cards waiting.
• Without the helpdesk licence, both endpoints answer 402.

Limits

What	Limit
Messages one chat account sends the app	20 a minute (“That’s a lot of messages at once. Wait a minute, then try again.”)
New requests and replies	The same limits as Get help
A message turned into a request	8,000 characters; the rest is cut (“(trimmed)”)
A request from the platform	256 KB (413 beyond)
Channels that open tickets	50
Test	10 a minute per person

In reports

Requests raised in chat have the ticket source Microsoft Teams or Slack, and reports count them under the channel Chat apps.

Privacy

• Merging a ticket moves its chat links to the ticket you keep, so replies keep reaching the chat the duplicate came from.
• Anonymising a ticket removes where it lived in chat and any card waiting for it.
• Removing an account removes its chat links, the chat threads of its requests and its waiting cards.
• A person’s data export lists the chat apps they are linked to and since when, and which of their requests were raised or followed in chat (direct chat or channel), each under its own number, even after a merge.

In the audit log

Action	Shown as
helpdesk.chat.settings_changed	Changed the chat app settings (the names of what changed, never a secret)
helpdesk.chat.disconnected	Disconnected a chat app
helpdesk.chat.tested	Tested a chat app connection (with whether it worked)
helpdesk.chat.request_raised	Raised a request from a chat app
helpdesk.chat.channel_ticket	Opened a ticket from a chat channel message
helpdesk.chat.approval_clicked	Answered an approval from a chat app (the decision itself is also recorded as usual)

Troubleshooting

Symptom or message	What to check
“Enter the tenant ID, a GUID like …, not a domain.”	Use the tenant’s GUID from the Entra admin center’s Overview, not a domain.
“Microsoft refused the app ID and client secret. …”	The secret has expired, or the app ID isn’t the bot’s Microsoft App ID.
“Microsoft didn’t recognise that tenant for this app. …”	Check the tenant ID, and that the bot is Single Tenant in that tenant.
“Slack refused the bot token. …”	Copy the Bot User OAuth Token (xoxb-…) again from OAuth & Permissions.
“… but the app is missing …”	Add the scopes listed above, then reinstall the app to the workspace.
“That doesn’t look like a bot token.” / “That doesn’t look like a signing secret.”	Paste the whole value, on one line.
Nothing happens when people message the app	The app is disconnected, the endpoint in the bot or app doesn’t match the page, or (Teams) the message came from another tenant.
People get “I couldn’t find your CompassDocs account…”	Teams: the directory sync is off, or their account isn’t linked to their directory entry. Slack: their Slack address isn’t the confirmed, unique address of their account.
“Open a chat with the CompassDocs app first, then try again.”	Message the app once, or install it for people (Teams setup policies).
An approver gets no card in Teams	Their personal chat with the app isn’t known yet: they need to message it, or have it installed.
A channel message doesn’t open a ticket	The channel isn’t listed for that app and trigger, the app isn’t in the channel, or (Teams) a reaction was used: Teams opens channel tickets only from a mention.
“The helpdesk isn’t taking requests in Teams right now. Use Get help in CompassDocs instead.”	Raise a request (and Follow and reply) are off for that app.