Connect an AI Teammate to Microsoft Teams

This reference explains how to connect one Alloy AI Teammate to Microsoft Teams through an Azure Bot. Use it when a customer wants to message an AI Teammate from Teams.

• An Alloy AI Teammate already exists.
• A Microsoft Azure administrator can create and configure an Azure Bot resource.
• A Microsoft Teams administrator can upload or approve custom apps for the tenant.
• Alloy automatically creates and maintains a default workflow for each AI Teammate. A missing default workflow is

a rare exception, usually caused by a failed setup, migration, or data issue. Teams messages can be saved before the workflow replies, but the AI will not respond until the sender is approved or enabled and the default workflow is present and runnable.

1. Open the AI Teammate detail page in Alloy.
2. Open the `MS Teams` tab.
3. Copy the `Messaging endpoint`. It has this shape:

```text https://{api-domain}/webhooks/msteams/messages/{organizationId}/{employeeId} ```

Alloy generates this endpoint from the organization and AI Teammate. The same tab is also where the Azure Bot credentials are saved and where the Teams app package is downloaded after connection.

1. In Microsoft Azure, open Marketplace and create an `Azure Bot`.
2. Choose the bot name and tenant/resource settings required by the customer's Azure policy.
3. When Azure asks for a Microsoft App ID, create a new Microsoft App ID unless the customer already has a

dedicated app registration for this bot.

1. Finish creating the bot resource.

The Azure administrator performs this step. Alloy does not create Azure resources automatically.

1. Open the Azure Bot resource.
2. Go to `Settings` -> `Configuration`.
3. Paste the Alloy `Messaging endpoint` into `Messaging endpoint`.
4. Keep the bot type aligned with the app registration:
5. `Single Tenant` requires an App Tenant ID in Alloy.
6. Multi-tenant bots can leave the tenant ID empty in Alloy.
7. Save the Azure Bot configuration.

In the Azure Bot configuration, copy:

• `Microsoft App ID`
• `App Tenant ID` when the bot is single-tenant

Then create a client secret for the app registration:

1. Open the app registration or the `Manage Password` / client secret flow from the Azure Bot page.
2. Create a new client secret.
3. Copy the secret value immediately. Azure only shows it once.

Back in Alloy:

1. Open the same AI Teammate `MS Teams` tab.
2. Click `Connect`.
3. Paste:
4. `Microsoft App ID` into the app ID field.
5. The client secret into the app password/client secret field.
6. `App Tenant ID` into the tenant field when applicable.
7. Save the connection.

Alloy stores the app ID and tenant ID for display. It does not return the app password through the read API.

In the Azure Bot resource:

1. Open `Channels`.
2. Add or enable the `Microsoft Teams` channel.
3. Accept the channel terms and save.

Without the Teams channel, the bot can exist in Azure but will not receive Teams messages.

After the Alloy connection is saved:

1. In Alloy, open the AI Teammate `MS Teams` tab.
2. Download the `Teams app package`.
3. In Microsoft Teams, open `Manage your apps`.
4. Choose `Upload app`.
5. Upload the ZIP package from Alloy.
6. Add the uploaded app to the required chat, group chat, team, or tenant app catalog according to the

customer's Teams policy.

1. Confirm the requested permissions and add the app.

The package contains a generated Teams manifest plus icons. The manifest uses the AI Teammate name and description, supports personal, team, and group chat scopes, and points Teams to the Azure Bot app ID.

When a Teams user sends the bot a message, Alloy creates or reuses a Teams contact channel and saves the conversation. Personal Teams chats are gated per contact. The AI Teammate only starts the workflow for a personal chat after that contact is approved for the teammate.

For Teams channels and group chats, Alloy creates a per-channel or per-group row after the bot has seen a message there. Newly discovered channels and groups are disabled by default. Enable the specific channel or group before allowing the bot to operate there.

Use the AI Teammate `MS Teams` tab or the API to:

• approve personal contacts before allowing AI replies there;
• enable specific Teams channels or group chats before allowing the bot to operate in them.

This prevents a newly uploaded Teams bot from automatically responding to every sender or shared conversation before an Alloy user reviews the scope.

• Teams webhook route:

`POST /webhooks/msteams/messages/{organizationId}/{employeeId}`

• AI Teammate Teams settings:
• `GET /api/organizations/{orgId}/employees/{employeeId}/msteams`
• `POST /api/organizations/{orgId}/employees/{employeeId}/msteams`
• `DELETE /api/organizations/{orgId}/employees/{employeeId}/msteams`
• Teams app package:

`GET /api/organizations/{orgId}/employees/{employeeId}/msteams/package`

• Approved Teams contacts:
• `GET /api/organizations/{orgId}/employees/{employeeId}/msteams/contacts`
• `POST /api/organizations/{orgId}/employees/{employeeId}/msteams/contacts/{contactId}`
• `DELETE /api/organizations/{orgId}/employees/{employeeId}/msteams/contacts/{contactId}`
• Known Teams channels and groups:
• `GET /api/organizations/{orgId}/employees/{employeeId}/msteams/channels`
• `PUT /api/organizations/{orgId}/employees/{employeeId}/msteams/channels/{channelId}/status`

Inbound Teams activities are accepted only when the employee has Teams credentials configured. Alloy ignores non-message activities, duplicate deliveries, and empty messages without downloadable attachments.

For accepted messages, Alloy stores the conversation, strips the bot mention from the prompt text, captures Teams routing metadata for replies, and starts the AI Teammate workflow only when:

• personal chats: the sender contact is approved for that AI Teammate;
• channels and group chats: that Teams channel or group is enabled for that AI Teammate;
• shared conversations address the bot with a mention, or reply inside a thread whose root addressed the bot.

If a reply `<at>`-mentions a different bot, the owning bot does not re-engage; the mentioned bot answers.

• automation is enabled for the conversation;
• the organization has available tokens;
• the AI Teammate default workflow is present and has a starting step.

Attachments are capped at `10` files, `10 MB` per file, and `30 MB` total per inbound message. Image attachments can be forwarded into the workflow input. Non-image attachments can be saved with the message but are not passed into the AI input payload.

During AI reply generation, Alloy sends a best-effort Bot Framework typing activity into the Teams conversation using stored Teams routing metadata.

• If Azure rejects messages, confirm the Azure Bot `Messaging endpoint` exactly matches the Alloy endpoint.
• If Teams cannot find the app, confirm the ZIP package was uploaded to the correct Teams tenant or app catalog.
• If messages reach Alloy but the AI does not reply, check the correct gate in the AI Teammate `MS Teams`

tab:

• personal chat -> approve the sender contact in `Contacts`
• channel or group chat -> enable that entry in `Channels`
• for channels and groups, confirm the message mentioned the bot or is in a thread whose root addressed the bot.

If the message mentions a different bot, the original bot yields to the mentioned one.

• then confirm the teammate default workflow is present and runnable; a missing default workflow is a rare setup

or data issue

• If replies fail in a single-tenant setup, confirm the tenant ID in Alloy matches the Azure app registration.
• If the app package cannot be downloaded, confirm the AI Teammate has a saved Microsoft App ID.