> ## Documentation Index
> Fetch the complete documentation index at: https://sofiedocs.usetransfer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up the Microsoft Teams integration

> Configure a single-tenant Azure Bot, distribute Sofie's Teams app, and verify linked-account conversations.

The Microsoft Teams integration lets users message or mention Sofie using their linked Sofie accounts. You configure the Microsoft app and Azure Bot, then distribute the Teams app package generated by Sofie.

Users complete a separate [Teams identity link](/integrations/microsoft-teams) in a personal chat. Microsoft 365 email, calendar, and file connections have their own [setup guide](/admin/integrations/microsoft-365).

## Before you start

You need:

* Access to Sofie **Organization Settings** > **Integrations**, with permission to edit integrations.
* Access to manage a Microsoft Entra app registration and an Azure Bot resource.
* Teams administrator access to distribute a custom app and make it available to your test users.
* Your Microsoft tenant ID and public Sofie HTTPS domain.
* Slack and Teams messaging integrations enabled for your Sofie deployment.

If the Teams section is missing, check availability with your Sofie administrator or TransferAI contact.

## Configure the Microsoft app and bot

<Steps>
  <Step title="Choose the Microsoft app registration">
    Use an app registration in the Microsoft tenant where you will install Sofie. Record its application client ID and directory tenant ID. Create a client secret and retain its **Value** for the Sofie settings field.

    The organization Teams setup uses the **Client ID**, **Client Secret**, and **Tenant ID** from Sofie's Microsoft integration card. If that card already supports Microsoft 365, coordinate changes with its owner because Teams reuses those credentials.
  </Step>

  <Step title="Register a single-tenant Azure Bot">
    Create an **Azure Bot** resource using the existing Microsoft app registration. Choose **Single Tenant** and use the same client ID and tenant ID that you will save in Sofie.

    Follow Microsoft's [Azure Bot registration guide](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration?view=azure-bot-service-4.0) for the resource creation flow.
  </Step>

  <Step title="Set the messaging endpoint">
    In the Azure Bot configuration, set the messaging endpoint to the URL below, using your public Sofie domain.

    ```text theme={null}
    https://<your-sofie-domain>/api/external-chat/teams/events
    ```
  </Step>

  <Step title="Enable the Microsoft Teams channel">
    In the Azure Bot's **Channels**, select **Microsoft Teams**, review the terms and messaging settings, and apply the configuration. See Microsoft's [Teams channel guide](https://learn.microsoft.com/en-us/azure/bot-service/channel-connect-teams?view=azure-bot-service-4.0).
  </Step>

  <Step title="Save the configuration in Sofie">
    Open **Organization Settings** > **Integrations**. In the Microsoft integration card, click **Show Details** under **OAuth Configuration**. Select **Use Organization OAuth App** for your organization-owned credentials. Enter **Client ID**, **Client Secret**, and **Tenant ID**.

    Turn on **Enable Microsoft Teams** and click **Save Changes**. Although the tenant field is labeled optional for Microsoft integrations, Teams requires a tenant ID.
  </Step>
</Steps>

<Note>
  Enter the client secret value, not its secret ID. Store it in the settings field and keep it out of chat, shared Workspaces, and training screenshots.
</Note>

## Download and distribute the Teams app

<Steps>
  <Step title="Download the package">
    After saving the Microsoft app details, click **Download Teams app**. Sofie generates a ZIP package with the app manifest and icons for the saved app ID and your Sofie domain.
  </Step>

  <Step title="Upload it to Teams">
    In the Teams admin center, open **Teams apps** > **Manage apps**. Use **Upload new app**, which may appear under **Actions**, and select the downloaded ZIP.

    Follow Microsoft's [custom app distribution guide](https://learn.microsoft.com/en-us/microsoftteams/upload-custom-apps). Make the app available to your test users under your organization's app policies.
  </Step>

  <Step title="Install it in the intended conversations">
    Add Sofie for personal use and to the team or group chat you want to test. The package supports personal chats, teams, and group chats.

    Review the conversation-message permissions during installation. Installing the app for personal use alone does not add it to a team or group chat.
  </Step>

  <Step title="Verify user linking and replies">
    Have a test user message Sofie in a personal chat and complete their account link. Send a request, then mention **@Sofie** in a test channel and follow up in the same thread.

    Check that the tenant appears in Sofie under **Workspace and tenant connections**. Run **Test connection**. Test actual replies as well as credentials.
  </Step>
</Steps>

## Review conversation-message permissions

Sofie's package requests resource-specific permissions to read messages in the team or chat where it is installed:

| Permission | Purpose |
| - | - |
| `ChannelMessage.Read.Group` | Receive team channel messages so a conversation can continue after the first mention. |
| `ChatMessage.Read.Chat` | Receive group-chat messages for follow-ups. |

These permissions are included in the Teams app package. Microsoft describes their scope and consent process in its [resource-specific consent guide](https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/rsc/resource-specific-consent).

Tell users that Sofie receives conversation messages in installed teams and group chats to support follow-ups without repeated mentions. Users still need their own Sofie account links. Replies in shared conversations are visible to other participants.

## Update the package for attachments

Teams app packages at version 1.2 or later enable attachments in personal chats. Save any configuration changes, download the current package, and upload it as an update to the existing Teams app.

In the Teams admin center, open the existing app's details and use **Upload file** to upload the updated ZIP. See Microsoft's [custom app update instructions](https://learn.microsoft.com/en-us/microsoftteams/upload-custom-apps#update-a-custom-app-using-teams-admin-center).

Test a supported attachment in a personal chat after the update. Teams channel and group-chat file access is not included yet.

## Allow automated posts

Sofie discovers destinations from installation activity and conversations. Destinations start inactive for outbound automation.

Use [Messaging destinations and connection health](/admin/integrations/messaging-destinations) to activate the intended destination, allow your automations, and test delivery.

## Troubleshooting

<Accordion title="Download Teams app is unavailable">
  Enable Teams and save the Microsoft client ID, client secret, and tenant ID first. Check the **Not configured** status and any **Setup incomplete** items.
</Accordion>

<Accordion title="The app is uploaded but does not appear for a user">
  Check the app's availability and your Teams custom app policies. Organization catalog changes can take time to appear. See Microsoft's [custom app settings guide](https://learn.microsoft.com/en-us/microsoftteams/teams-custom-app-policies-and-settings).
</Accordion>

<Accordion title="The app does not respond">
  Confirm that the Azure Bot and Sofie use the same app ID and tenant ID. Check the client secret value and expiration, messaging endpoint, and enabled Teams channel. Confirm that the app is installed in the conversation you are testing.
</Accordion>

<Accordion title="Mentions work but follow-ups do not">
  Check that the installed package includes the conversation-message permissions. Update the existing app and review the required consent. Test a reply in the same thread after mentioning Sofie.
</Accordion>

<Accordion title="Personal-chat attachments do not work">
  Confirm that the installed package is version 1.2 or later. Download the current package from Sofie and update the existing app. Test in a personal chat rather than a channel or group chat.
</Accordion>

## Related guides

* [Use Sofie with Microsoft Teams](/integrations/microsoft-teams)
* [Messaging destinations and connection health](/admin/integrations/messaging-destinations)
* [Microsoft 365 integration](/admin/integrations/microsoft-365)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.