Teams Bot Connection

Function Description

This document describes how to apply for and configure a Teams bot, ultimately allowing the agent on the Dora platform to receive user messages, process files, and proactively push messages via Microsoft Teams.

Prerequisite

Before starting the configuration, ensure that the following prerequisites have been met:

(1) You have an available Microsoft 365/Teams tenant.

(2) You have an account that can access the Azure portal/Microsoft Entra.

(3) The account has permissions to create or manage the following resources:

• App Registration

• Azure Bot

• Microsoft Teams Channel

(4) The Teams tenant can upload custom apps.

(5) The FineBI Java service has a public HTTPS address.

(6) The Java service can access the intranet Python fine-im service.

Effect Demonstration

Taking the scenario of asking the bot for the total sales amount in the 2025 on the Teams client as an example, the following figure shows the effect.

Applying for a Teams Bot

(1) Access the Azure portal, and choose Microsoft Entra ID > Manage > App registrations > New registration to create an application, as shown in the following figure.

(2) Set the app configuration items and click Register. The following table lists configuration instructions.

(3) After creation, find and record the followings on the Overview page:

• Application (client) ID

• Directory (tenant) ID

Adding a Client Secret

(1) Choose Manage > Certificates & secrets > Client secrets > New client secret, enter the description according to business requirements, adjust the expiration time, and click Add.

(2) After creation, immediately copy and save the secret value.

Note:

(1) You must save the value of the client secret, rather than the secret ID.

(2) The value of the client secret can only be copied at the time of creation. Copy it immediately. Once the page is closed, the value cannot be retrieved again.

Creating an Azure Bot

(1) Search for Azure Bot and create an Azure bot resource in the Azure portal.

(2) Set Creation type to Using existing app registration. Enter the values of Application (client) ID and Directory (tenant) ID recorded in the "Applying for a Teams Bot" section, and set the remaining configuration items as required.

(3) After creation, wait until you are automatically redirected to the bot overview page. Choose Go to resource > Settings > Configuration, set Messaging endpoint, and click Apply.

The messaging endpoint must be in the https://{public domain}/webroot/decision/ai/conversation/im/teams/messages/{Microsoft app ID} format, where the Microsoft app ID is the value of Microsoft App ID displayed on this page.

Note:

(1) The HTTPS protocol must be used, and the certificate must be valid and not expired.

(2) The {Microsoft app ID} placeholder at the end of the URL must exactly match the app ID configured in the Dora system.

(3) The final forwarding target of the reverse proxy must be a Java service and cannot point directly to a Python service.

(4) When the reverse proxy forwards requests, the Authorization field in the request header must be fully kept.

(5) The Java service must be able to normally access the intranet Python fine-im service.

Enabling the Teams Channel

(1) Choose Settings > Channels and click Microsoft Teams.

(2) Tick the agreement checkbox, click Agree, and click Apply.

Configuring the Teams Bot in the Agent

Access the target agent, click Connected IM Tool, add/edit the Microsoft Teams bot, enter the following information, and save the settings.

• App ID: Application (client) ID

• App Secret: Value of the client secret

• Tenant ID: Directory (tenant) ID

Getting the App Package and Uploading It to Teams

Getting the App Package

Method One: Direct Download in the Agent

Choose Admin Console > Agent Management, select the target agent, click Connected IM Tool, add/edit the Microsoft Teams bot, and directly download the corresponding app package.

Method Two: Manual Packaging

(1) Prepare three files (manifest.json, color.png, and outline.png) and compress them into a ZIP file.

The following table lists core field requirements for manifest.json.

(2) Directly place the three files mentioned above in the root directory of the ZIP file. After decompression, these three files must be visible directly in the first-level directory.

Uploading a Custom App on the Teams Client

Log in to the Teams client, choose Apps > Manage your apps, and upload the app package obtained in the previous step to the Teams client.

Note:

If no upload entry is available, the custom app permission has not been enabled for the tenant policy. You need to contact the Teams administrator to enable it. Find the uploaded app and click Add to complete the installation.

Adding the App to the Client

After the app is uploaded successfully, the corresponding app card will appear on the page. Click the Add button in the card to bring up a pop-up box, and then click Add in the pop-up box to add the bot app to the Teams client, as shown in the following figure.

Configuring Teams User Mappings

Choose User Management > IM User Mapping > Teams and map enterprise accounts with Teams accounts.

Open a private chat window with the bot in Teams and send a message to test the chat, file processing, and message push functions.

Message Sent in Teams But Not Received by the System

Check the following content:

(1) Whether the messaging endpoint address of the Azure bot is entered correctly

(2) Whether the endpoint points to the Java service

(3) Whether the public HTTPS address can access the Java/FineBI service normally

(4) Whether the Java service has successfully forwarded the request to Python fine-im

(5) Whether the reverse proxy has fully passed through the Authorization request header

(6) Whether the value of botId in the manifest file of the Teams app is equal to the value of App ID

(7) Whether the Microsoft Teams channel has been enabled for the Azure bot

(8) Whether the corresponding Teams bot has been bound to the Dora console

Unavailable App Secret

Check the following content:

(1) Whether the value of the client secret, rather than the secret ID, is entered in the Dora system

(2) Whether the client secret has expired

(3) Whether the app ID and secret come from the same app registration

Error: CONNECTION_NOT_FOUND

Common causes:

• The {AppID} in the callback path does not match the app ID bound in Dora.

• Teams messages have been forwarded to the backend AI, but the Teams bot binding has not been completed in Dora.

• Connection recovery fails after the AI service is restarted.

Error: CHANNEL_DELIVERY_FAILED

Common causes:

• Bot Framework token validation fails.

• The Java service/reverse proxy does not pass through the Authorization request header.

• Java cannot connect to the Python forwarding address.

• The Teams message structure does not match the expected format of the parser.

Error: MISSING_REFERENCE

Common causes:

• The target user has not sent a private message to the bot.

• The account configured in the user mapping does not match the external ID carried in the callback.

• Chat-referenced data has not migrated after environment switchover.