Microsoft Teams Messaging Channel

The Teams messaging channel lets users chat with the MCintelligentplus agent from a Microsoft Teams personal chat. MCintelligentplus runs a single system-level Teams bot — there is no per-organization bot or default-workspace setting anymore (that configuration was removed in #916).

Step 1: Register an Azure Bot

1. Go to portal.azure.com → Create a resource → Azure Bot.
2. Choose a bot handle and select Multi Tenant or Single Tenant based on your needs.
3. Under Microsoft App ID, choose Create new to auto-generate an App Registration.

Step 2: Get the App ID and Password

1. The Bot App ID is the Application (client) ID from the App Registration.
2. The Tenant ID is the Directory (tenant) ID — leave it blank for multi-tenant bots.
3. For the Bot App Password, open the App Registration → Certificates & secrets → New client secret, and copy the secret value — Azure shows it only once.

Step 3: Set the Messaging Endpoint

1. In the Azure Bot resource → Configuration → Messaging endpoint.
2. Set it to:

https://<your-domain>/api/v1/gateway/webhooks/teams/system

3. Enable the Microsoft Teams channel under Channels.

The endpoint must be reachable over public HTTPS.

Step 4: Configure the Bot in MCintelligentplus

System bot settings live in the admin portal at Admin → Message → Teams (/admin/message/teams):

The values are DB-first: the admin portal value wins, then the environment variable, then the default. Changes take effect without a restart, and the master switch GATEWAY_ENABLED=TRUE must also be set for the messaging gateway to run.

Pairing Flow

1. The user opens User Settings > Messaging Channels and clicks Pair Teams.
2. MCintelligentplus shows a pairing command: /start <CODE>.
3. The user opens Microsoft Teams, finds the MCintelligentplus bot in their chats, and sends that command.

Teams has no deep link, so the code must be sent manually. Pairing codes expire; if yours expires before you send it, generate a new one.

Users with the same email in Teams and MCintelligentplus are matched automatically: on the first message, MCintelligentplus reads the user's email through the Bot Framework roster API and binds the chat to the user's first workspace membership, so no pairing code is needed. If no match is found, the bot sends onboarding instructions pointing back to the pairing flow.

Runtime Behavior

1. Teams sends the bot activity to POST /api/v1/gateway/webhooks/teams/system.
2. MCintelligentplus validates the Bot Framework JWT, applies a 256 KB body cap, and accepts only personal conversations.
3. The activity is persisted to the gateway inbox, deduplicated by activity ID.
4. The worker resolves the Teams user to a MCintelligentplus user and workspace (existing binding, roster API email match, or a /start pairing).
5. The agent runs with that user's permissions and the reply is posted back in the same Teams chat.

In the bot chat, /workspace switches the bound workspace, /new starts a new conversation, and /start <CODE> completes a pairing.

Access Control

• Members of an organization need the Teams channel enabled for them. Org admins toggle this per member on the org portal's Members page (teams_enabled). Users with no organization membership are allowed.
• Changes to the bot configuration are recorded in the audit log.

See Messaging Channels Troubleshooting if the bot does not reply.