Microsoft Teams intake

Admin, Messages, Teams (/admin/notifications). Needs connector.manage and the Tickets module. From 0.21.0.

A teacher messages the school’s IT bot in Teams, in a chat or by @mentioning it in a channel, and a ticket opens as if they had emailed the desk. Replying in the same thread or chat adds to the same ticket, and when the desk answers or closes it, the teacher hears about it in the same conversation.

Teams joins the same intake as email rather than running beside it. The requester is matched the same way, an unknown sender is handled the same way, tickets route to the same default department, and every step is audited in the same place.

Not yet run against a live Teams tenant

This release has been tested against Microsoft’s documented token, message and reply formats, not against a school’s own Teams tenant and Azure Bot. The generated Teams app package has not yet been through Microsoft’s app validator. If you set it up, tell us what you see, particularly anything in the troubleshooting table that does not match.

Before you start

You need	Why
A Microsoft Entra ID connector with an application (client) ID and secret, in Admin, Connectors	The bot signs in as that same app registration. There is no second secret to create, store or rotate
Your Entra tenant ID, the GUID on the Microsoft Entra admin centre overview page	Messages from any other Entra tenant are refused
Rights to create an Azure Bot resource in the school’s Azure subscription	Microsoft delivers Teams messages to a bot through it
A Teams administrator who can upload a custom app in the Teams admin centre	Staff reach the bot through that app
Plugboard reachable from the internet over HTTPS	Microsoft calls your deployment. On a self-hosted install PUBLIC_URL must be an https:// address; see environment variables

The bot’s token from Microsoft needs no Microsoft Graph permission, so using the Entra connector’s registration adds nothing to what that registration can do in your directory.

Setting it up

1. Create the Azure Bot

In the Azure portal, create an Azure Bot that uses the existing app registration of your Entra connector, as a single-tenant bot. Microsoft no longer allows new multi-tenant bots, and a single-tenant bot in your own tenant is what Plugboard expects.

Set its messaging endpoint to:

https://<your Plugboard address>/api/webhooks/teams/messages

The Teams tab shows this exact address once you have saved the bot. Then add the Microsoft Teams channel to the bot, as Microsoft’s bot documentation describes.

2. Save the bot in Plugboard

On Admin, Messages, Teams:

Field
Entra connector	Which Entra connector’s app registration the bot uses
Entra tenant ID	The GUID from step one’s tenant
Bot name in Teams	Up to 30 characters. IT Help by default
Accept messages from Teams	The off switch

Press Save. The panel then shows the app ID it read from the connector, the bot’s status and the messaging endpoint.

3. Test it

Press Test. Plugboard asks Microsoft for a bot token, using the connector’s real secret, from your Entra tenant. Only a school that holds that secret, in that tenant, can pass.

Nothing from Teams is accepted until a test has passed, and every save clears it. A bot that has not been tested since its last change refuses every message, and the status says so rather than showing a green light it has not earned. The test and every change are recorded in the audit log; the secret never is.

4. Upload the Teams app

Press Download Teams app. You get plugboard-teams-app.zip, generated from your saved settings: a manifest naming your bot, and two icons. Do not edit it; download it again after a change instead.

In the Teams admin centre, upload it as a custom app and make it available to the staff who should use it through your app setup or permission policies. The app works in personal chats, group chats and team channels. Its privacy and terms links point at plugboard.app/privacy and plugboard.app/terms.

How messages become tickets

In a personal chat, any message reaches the bot. In a channel or group chat, the bot only receives messages that @mention it; that is how Teams works, not a Plugboard setting.

Where	What happens
A new channel post that @mentions the bot	Opens a ticket
A reply in that thread that @mentions the bot	Comments on the same ticket, whatever its status, the way a reply to a ticket email does
A chat message	Joins the most recent ticket from that chat that is still open. With none, it opens a new one
A chat message starting new:	Always opens a new ticket

In chats, the bot answers added to #412, so the teacher knows which ticket the message joined and that new: starts another. A channel thread is itself the ticket and is not told again.

The subject is the message’s first line, up to 120 characters, with the bot’s own @mention removed.

Edited and deleted messages are ignored. The desk keeps what was received, as it does with an email the sender later regrets. Applying a delete would let a requester remove something the desk may already have acted on.

Attachments are recorded by name only, as a line on the comment: Attached in Teams, not copied: diagram.png. Files and images are not copied into Plugboard, and no link to them is kept, because a pre-authorised download link on a ticket would hand the file to everybody who can read the ticket. Ask for the file by email or through the portal if the desk needs it.

Who the requester is

The requester is identified by their Entra object ID, never by the display name in the message:

1. A person already linked to that Entra account through the directory connector.
2. Otherwise, the email address your directory holds for that object ID, matched to a person in Plugboard.
3. Otherwise, the sender is unknown.

An unknown sender is handled as an unknown email address is: the ticket opens with no requester, and an internal note names them, for example Sam Lee (Teams, Entra object ID …). Their later messages are added as public comments under that label.

What is posted back

The bot posts the same messages email would send, from the same place, so the two cannot drift apart:

When	In a personal chat	In a channel or group chat
Teams opens a ticket	The Ticket received message	The Ticket received message
The desk replies in public	The reply itself	Only a pointer, such as #412 has a reply from the desk. Never the reply
The ticket is first closed	The Ticket closed message	The Ticket closed message

A desk reply written for one person is not posted where a whole channel can read it. Internal notes never reach Teams.

The wording is your own email message text, greeting and all, and a message switched off there is switched off in Teams too. The requester is still emailed as before; Teams is in addition, not instead.

Replies go only to Microsoft’s public Bot Connector service. A slow or failed post to Teams never holds up or fails the desk’s reply or close; it is logged.

Privacy

The bot relays what staff type to it into tickets, which the school controls like any other ticket. For each message, Plugboard keeps the conversation details it needs to reply, including the sender’s Entra object ID. An unknown sender’s display name appears only in the ticket’s internal note and comment labels, as an unknown email address would.

An erasure request clears the person’s Entra object ID from Teams message records. Records of messages that opened no ticket are deleted once they pass the school’s data retention window; the rest go with their ticket.

Not supported

• Microsoft’s government clouds (GCC, GCC High, DoD). Public cloud only.
• Slack, or any chat service other than Teams.
• Copying files or images from Teams.
• Adaptive Card forms, message extensions and meeting apps.
• The bot starting a conversation with somebody who has never messaged it.
• A Teams-specific set of message wording. Chats receive the email text.
• Choosing a department for the bot. Tickets follow your default routing.

On a self-hosted install that runs more than one API process behind one database, two Teams messages arriving together in the same chat could open two tickets. Every current deployment shape runs one API process per host.

Troubleshooting

Symptom	Cause
The tab says to add an Entra connector first	No Microsoft Entra ID connector with an application ID and secret exists yet
The messaging endpoint says to set PUBLIC_URL	The deployment’s public address is not https://. Microsoft only calls HTTPS endpoints
Test fails	The Entra tenant ID is wrong, the connector’s secret has expired or been replaced, or the app registration belongs to a different tenant
Status says the connector now uses a different app registration	The Entra connector’s client ID changed after the bot was saved. Save and test again, then download and upload the Teams app again
Messages get no reply and open no ticket	The bot has not passed a test since its last save, Accept messages from Teams is off, the Tickets module is off, or the Azure Bot’s messaging endpoint or Teams channel is wrong
Nothing happens in a channel	The message did not @mention the bot
A message from another organisation is refused	Only your own Entra tenant is accepted. The refusal is in the audit log
A chat message joined an old ticket	It was still open. Start the message with new:
The requester is blank and an internal note names the sender	Their Entra account is not linked to anyone in Plugboard, and your directory’s email for them matches no person. Link or add the person
A channel got a pointer rather than the reply	Deliberate. Replies are only posted in full in a personal chat
No Teams message for a reply	The matching email message is switched off, or the reply was an internal note