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.
• The AI Teammate has a published workflow. Teams messages are saved even without a workflow, but the AI will

not reply until the teammate has an active workflow and the sender is approved.

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. The AI Teammate only starts the workflow after that contact is approved for the teammate.

Use the AI Teammate `MS Teams` tab or the API to approve the contact. This prevents a newly uploaded Teams bot from automatically responding to every sender before an Alloy user reviews the contact.

• 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}`

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:

• the sender contact is approved for that AI Teammate;
• automation is enabled for the conversation;
• the organization has available tokens;
• the AI Teammate has an active workflow with a starting step.

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.

• 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, approve the sender contact in the AI Teammate `MS Teams`

tab and confirm the teammate has an active workflow.

• 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.