1. Introduction

With the Teams Agent, users ask Manage for TEOS questions from within Microsoft Teams. To set it up, you create an Azure Bot and an OpenAI API key, and enter those details in the Teams Agent configuration. For an on-premises installation you also set up port forwarding.

Teams sends each message through the Azure Bot to the Teams Agent. The agent uses OpenAI to understand the question and retrieves the data from Manage for TEOS through the MCP server.

2. What you need

You need the following before you start:

• An Azure subscription in your organization's Microsoft 365 tenant, with permission to create resources and app registrations (for example the Contributor role on a resource group and Application Developer in Entra ID).
• A Teams administrator who can approve an app for the organization.
• An OpenAI account with a payment method or credit.
• For on-premises: a public DNS name for the TEOS server with a valid, publicly trusted certificate, and access to the firewall or router.

You collect the following values during the steps. Store them securely, for example in a password manager.

3. Create the Azure Bot

The Azure Bot connects Microsoft Teams to the Teams Agent on your TEOS server.

1. Sign in to portal.azure.com with an account from your organization's tenant.
2. Select Create a resource, search for Azure Bot and select Create.
3. Fill in the Basics tab:
   • Bot handle: a unique name, for example teos-teams-agent.
   • Subscription and Resource group: as you prefer; create a new resource group if needed.
   • Data residency: Regional, then select region.
   • Pricing tier: Standard or Free (F0). Microsoft Teams is a standard channel, so there are no message charges.
   • Type of App: Single Tenant. This must match "MicrosoftAppType": "SingleTenant" in the configuration.
   • Creation type: Create new Microsoft App ID.
4. Select Review + create and then Create.
5. Wait until the deployment is complete and select Go to resource.

Button and field names may differ slightly depending on the language of the Azure portal.
 

4. Get the App ID, tenant ID and client secret

The Teams Agent uses these three values to sign in to Microsoft.

1. In the Azure Bot, open Settings → Configuration.
2. Note the Microsoft App ID and the App Tenant ID.
3. Select Manage Password next to the App ID. The related app registration in Microsoft Entra ID opens.
4. Go to Certificates & secrets → Client secrets and select New client secret.
5. Enter a description, for example TEOS Teams Agent, choose an expiry period and select Add.
6. Copy the Value of the secret immediately. It is no longer shown once you leave the page.

Use the Value, not the Secret ID. When the secret expires, the bot stops working: create a new secret in time and update MicrosoftAppPassword (section 9). Put the expiry date in your calendar.
 

5. Set the messaging endpoint

The messaging endpoint tells Azure where to send the Teams messages. It is always the public address of the agent followed by /api/messages.

1. In the Azure Bot, open Settings → Configuration.
2. Under Messaging endpoint, enter the address that matches your installation (see the table).
3. Select Apply.

6. Connect the bot to Microsoft Teams

First you connect the Teams channel to the bot, then you make the bot available to users as an app.

Connect the Teams channel

1. In the Azure Bot, open Settings → Channels.
2. Select Microsoft Teams, accept the terms and choose Microsoft Teams Commercial for messaging.
3. Select Apply. With the Open in Teams link you can try the bot yourself straight away.
    

7. Make the bot available to users

The Teams Agent is added to Teams with an app package: a .zip file containing manifest.json, color.png and outline.png. The package must contain your own Microsoft App ID and host name. TEOS Support can prepare it for you based on the values from section 4, or you can adapt it yourself:

1. Extract the .zip file and open manifest.json in a text editor.
2. Replace the value of "id" and of "botId" (under "bots") with the Microsoft App ID from section 4.
3. Under "validDomains", replace <customername>.teosmanage.com with the host name of your TEOS environment, without https:// and without a port, for example teos.example.com.
4. Save the file and create a new .zip of manifest.json, color.png and outline.png. Place the three files directly in the root of the .zip, not in a subfolder.
5. Sign in to the Teams admin center and go to Teams apps → Manage apps.
6. Select Actions → Upload new app and choose the .zip file.
7. Make sure the app status is Allowed. Optionally assign the app to users through an app setup policy under Teams apps → Setup policies.

Whether users can add the app themselves depends on your organization's app policies.

 

8. Create an OpenAI API key

The Teams Agent uses an OpenAI language model to understand and answer questions. Usage is billed to your organization's OpenAI account.

1. Sign in to platform.openai.com.
2. Make sure there is a payment method or credit under Settings → Billing. Without credit, OpenAI rejects the requests.
3. Go to API keys and select Create new secret key.
4. Enter a name for the key, for example TEOS Teams Agent, choose the project and select Create secret key.
5. Copy the key immediately. It is shown only once.

The model is already set in the configuration ("Model": "gpt-5.4-mini"). Only change it in consultation with TEOS. Optionally set a monthly limit under Settings → Limits to keep costs under control.

 

9. Port forwarding and certificate (on-premises only)

Azure must be able to reach the TEOS server from the internet over HTTPS. If port 443 does not lead directly to the TEOS server, forward another public port. Skip this section for TEOS Cloud.

1. Choose a free public port, for example 8126.
2. Create a rule in your firewall or router: inbound TCP on the public port to the internal IP address of the TEOS server, port 443.
3. Make sure the public DNS name (for example teos.example.com) points to your public IP address.
4. Check that the TEOS site in IIS uses a valid, publicly trusted certificate for that name. Azure refuses connections with a self-signed or expired certificate.
5. Use the same host name and port in the messaging endpoint (section 5) and in BotPublicBaseUrl (section 9).

To restrict traffic to Microsoft, only allow the IP ranges of the AzureBotService service tag. Microsoft publishes these as a downloadable list, which changes periodically.

Check from a device outside your network: https://<your-host>:<port>/agent/ must load without a certificate warning. A 404 message is normal here.

10. Enter the values in the Teams Agent

The collected values go into appsettings.json of the Teams Agent.

• TEOS Cloud: send the values to TEOS Support through a secure channel (never by regular e-mail). Support enters them and restarts the agent.
• On-premises: you enter them yourself, by default in C:\Program Files\TEOS Manage\www\TeamsAgent\appsettings.json.

1. Make a copy of the file first.
2. Open the file as administrator in a text editor, for example Notepad.
3. Replace the four placeholders between < > with your own values, including the brackets. Keep the quotation marks.
4. Check BotPublicBaseUrl: for on-premises with another port, add that port (see section 5).
5. Save the file and restart the agent: in IIS Manager → Application Pools → Teams-Agent → Recycle.
    

11. Testing and troubleshooting

Test in Azure first and then in Teams.

1. In the Azure Bot, open Test in Web Chat and send a question, for example "Which devices are offline?".
2. If you get an answer, open the app in Teams and ask the same question.

If you cannot resolve it, send TEOS Support a description of the message and the time it occurred. On-premises, the agent's log files are in www\TeamsAgent\logs. Never include the client secret or the API key.
 

12. Revision History

13. Need help?

Our support team is available Mon–Fri, 9:00–17:00 CET

Support portal: https://helpdesk.teos.solutions/

Email: support@teos.solutions

Phone: +31 582038380

Report a bug or suggest a feature

Found something that isn’t working, or have an idea? 
Send us an email (see above). We read every submission.

© 2026. TEOS Solutions B.V., part of ScreenCom Group. All rights reserved.