Teams

Connect an Understand Tech Assistant to Microsoft Teams

Expected outcome for the customer

In Microsoft Teams, your assistant will appear as a chat bot in a 1:1 chat (private conversation).

The customer only needs to:

1. Create an Azure Bot

2. Register your Azure bot in app.understand.tech (app ID, 1 secret value)

3. Create and install the Teams app package

---

Client prerequisites

The customer must have:

• An Understand Tech assistant already created beforehand to be used in Teams

• An API key authorized to act on behalf of end users (is_external_usage = true)

---

What Understand Tech provides

• Teams Messaging Endpoint URL (hosted by Understand Tech): https://api.understand.tech/integrations/teams/messages

• Assistant ID — unique identifier of your assistant Example: https://api.understand.tech/integrations/teams/messages

---

Steps to connect the assistant to Teams

1

Step 1: Create the bot in Azure

1. Log in to Azure Portal

2. Create a resource → Azure Bot (Azure AI Bot Service)

3. Choose the tenant type: Single Tenant (this cannot be changed once created)

1. Once created, go to Settings → Channels, add Microsoft Teams — you should see Teams with a "Healthy" status

Note the following information to register your app in app.understand.tech:

• Microsoft App ID: unique identifier of your bot in Azure → Azure Portal: Home → Bot services → your bot → Settings / Configuration

• App Tenant ID: found at the same location

• App Registration ID: unique identifier of your app registration in Azure Active Directory → Azure Portal: Home → App Registrations → your app → Overview → Application (client) ID

💡 This value may be the same as your Microsoft App ID, depending on how your bot was created.

• Client Secret (value): acts as a password for your bot, allowing Teams to authenticate securely with Azure

To create a Client Secret:

1. Go to Home → App Registrations → your app → Manage / Certificates & Secrets

2. Give it a name, choose an expiration period, and click Add

3. Copy the value immediately — it is only visible once

⚠️ Important security note: Never share this client secret publicly. Treat it like a password. If it is compromised, regenerate it in Azure immediately.

In this setup, the endpoint is hosted by Understand Tech. The customer does not need to host any server.

---

2

Step 2: Configure the Messaging Endpoint

1. Go to your Azure Bot service → select your bot → Settings → Configuration

2. In the Messaging Endpoint field, paste the URL provided by Understand Tech: https://api.understand.tech/integrations/teams/messages

3. Click Apply

Teams messages will now reach your Understand Tech assistant directly.

3

---

Step 3: Register the bot in app.understand.tech

Complete the registration in the Understand Tech portal using the information collected in the previous steps:

Field	Where to find it
Integration type	Select Microsoft Teams
App ID	Azure Portal: Home → Bot services → your bot → Settings / Configuration → Microsoft App ID
App Secret	Azure Portal: Home → App Registrations → your app → Certificates & Secrets → Client Secret value
Tenant ID	Azure Portal: Home → Bot services → your bot → Settings / Configuration → App Tenant ID
Token App ID	Azure Portal: Home → App Registrations → your app → Overview → Application (client) ID
API Key	Understand Tech Developer Portal
Assistant ID	app.understand.tech → Workspace → your assistant

---

4

Step 4: Create and Install the Teams App (Developer Portal)

Use the Developer Portal for Teams to generate and upload the app.

A) Open Developer Portal in Teams

• In Microsoft Teams: Apps → Manage your apps → Developer Portal

• Or use the direct link: Developer Portal for Teams

B) Create a New App

1. Click Create new app

2. Fill in the basic info:

   • App name (e.g., UT Bot)

   • Short name & short description

   • Developer info (name, website, Privacy & Terms URLs)

3. Add app icons (Configure / Branding):

   • Outline: 32×32 px PNG

   • Color: 192×192 px PNG

4. Click Save

C) Add Your Bot

1. Go to Configure / App Features → Bots → Add

2. Choose Existing bot

3. Paste your Microsoft App ID (Azure Bot → Settings / Configuration → Microsoft App ID)

4. Set Scopes:

   • Personal → 1:1 private chat

   • Team → bot available in channels

5. Click Save

D) Set Permissions

Go to Configure / App Features → Bots → Authorization

Teams Permissions — Application:

• ChannelMessage.Read.Group

• ChannelMessage.Send.Group

• TeamsActivity.Send.Group

Chat / Meeting Permissions:

• ChatMember.Read.Chat

• ChatMessage.Read.Chat

• ChatMessage.Send.Chat

• TeamsActivity.Send.Chat

Click Save.

E) Publish to your organization Click Publish / Publish to org -> Submit app update

Or Open Microsoft Teams

• Click Apps, then Manage your apps

• Upload an app.

• Select your app to submit

The bot is now installed in Teams for your organization and can be added to a personal chat or a channel.

---

5

Step 5: Test the bot

A) Open Microsoft Teams

Launch the Teams application (desktop, web, or mobile).

B) Add the bot

1. Go to Apps in the left-hand menu

2. Search for the app you just created (e.g., UT Teams Bot)

3. Click Add to install it.

💡 If it doesn't appear, try refreshing Teams, signing out and back in, or reinstalling the app.

C) Start a conversation

Open a private chat with the bot and type a message, for example: Hello

D) Wait for the assistant's reply

The bot will forward your message to the Understand Tech backend and you will receive the assistant's response in the chat.

---

Troubleshooting checklist

Issue	Solution
Bot added but does not respond	Verify the Messaging Endpoint URL is correct: https://api.understand.tech/integrations/teams/<assistant_id>/messages
Teams channel not enabled	Go to your Azure Bot resource and enable Microsoft Teams under Channels
HTTPS required	The endpoint must be public and secure (HTTPS)
401 / Unauthorized	Your API key may be missing, invalid, expired. Check at the Understand Tech Developer Portal
Users cannot see the bot	A tenant policy may block sideloading. Use the Teams Admin Center to manage app permissions