Microsoft Teams

Microsoft Teams channel

Since 3.1.0 · Contributed by Andrew Turbay (@turbay-a) in PR #166 · How it works underneath: Teams and Mattermost — Developer Guide

People in your organisation chat to a service desk bot in Teams, one to one. Each conversation becomes a ticket, exactly like email, WhatsApp and Telegram, and analysts reply from the ticket's chat box.

FreeITSM talks to the Bot Framework only. It makes no Microsoft Graph calls, so the bot needs no Graph permissions.

---

What you need

• Global Administrator (or Application Administrator) on the Microsoft 365 tenant.
• The Azure portal (portal.azure.com) and the Teams Admin Center (admin.teams.microsoft.com).
• A public https address for this FreeITSM install, set on Tickets → Settings → Messaging. Teams only delivers to https, and it fetches the images you send from the same address.

1. Register the application

1. Azure portal → Microsoft Entra ID → App registrations → New registration.
2. Name it, for example FreeITSM Teams bot.
3. Supported account types: Accounts in this organizational directory only (Single tenant). No redirect URI.
4. Register, then copy:
   • Application (client) ID → Bot App ID in FreeITSM
   • Directory (tenant) ID → Tenant ID in FreeITSM

2. Create a client secret

Certificates & secrets → New client secret. Copy the secret's Value (not its ID) into App secret — Azure shows it once. Note the expiry date: when it passes, the bot stops until you add a new one.

3. Create the Azure Bot

1. Create a resource → Azure Bot → Create. Type of app: Single Tenant; Use existing app registration with the same App ID and tenant.
2. Open it → Configuration → Messaging endpoint: the webhook URL from FreeITSM's channel list (https://<your-address>/api/messaging/webhook.php?channel=<id>). Apply.
3. Channels → add Microsoft Teams → accept → save.

4. Add the channel in FreeITSM

Tickets → Settings → Messaging → Add channel, provider Microsoft Teams. Fill in Bot App ID, Tenant ID and App secret, Save, then Test connection — green means Microsoft issued a token for the app.

5. Install the app in Teams

Open the saved channel → Download Teams app package. You get a zip with the manifest and two icons, built from your App ID. In the Teams Admin Center → Teams apps → Manage apps → Upload new app, choose it, then make sure it's published and available to the people who should use it.

The manifest's website, privacy and terms links point at this install, because Teams insists on https links there. Change them in the Teams Admin Center if your company has its own pages.

6. Try it

Find the bot under Chat in Teams and send a message. A ticket appears with the Teams origin. Reply from the ticket and the answer arrives in the same Teams chat.

---

Good to know

• Only your own organisation. Only people in the Microsoft 365 tenant you entered can open tickets through the bot. A message from anyone else is refused, even if they find the bot.
• One-to-one chats only. Group chats and channels are ignored — one conversation there is shared by many people.
• No first contact. The bot can only answer people who have written to it first.
• Matched to the person you already have. FreeITSM asks Teams for the person's email (from your Microsoft 365 directory, no extra permission needed). If someone in FreeITSM has that email, the ticket is theirs, with their other tickets and their company. If not, they become a contact with their real name.
• Images only, outbound. A picture you attach is sent to Teams; other files are refused with a clear message. Microsoft fetches the picture from /api/messaging/media.php, so that path must be reachable from the internet with no login in front of it.
• Ratings. If Tickets → Settings → CSAT → Ask chat customers in their chat is on, the customer gets their rating question in Teams with five buttons.
• No read receipts.

Troubleshooting

Symptom	Likely cause
Test connection: AADSTS700016	The Tenant ID is wrong, or the app isn't in that tenant.
Test connection: invalid_client	The secret is wrong or has expired — create a new one and paste its Value.
The bot doesn't answer	The Messaging endpoint isn't the webhook URL, or the Microsoft Teams channel isn't enabled on the Azure Bot.
Messages are refused (403)	The App ID or Tenant ID in FreeITSM doesn't match the Azure Bot — or the person writing is in another organisation.
Images show as broken	/api/messaging/media.php isn't reachable from the internet, or a proxy blocks Microsoft.
People can't find the app	It isn't published or available to them (Teams Admin Center → Manage apps).

---

Related: Mattermost channel · Slack channel · Telegram channel · Teams and Mattermost — Developer Guide