Skip to main content

Microsoft Teams Integration

Connect your Microsoft Teams tenant to Phoenix so OttoBot can respond to your team's messages in Teams, under your organization's data boundary.

Prerequisites​

Before you begin, ensure you have:

  • An Azure subscription with permission to create an Azure Bot resource
  • Permission to register applications in your Microsoft Entra ID (formerly Azure AD) directory
  • Permission to upload or install an app in your Microsoft Teams tenant
  • Admin access to your Phoenix organization's Integrations settings

You will collect four values from the Azure portal and paste them into Phoenix.

What you need to collect​

ValueWhere it comes from
App (Client) IDYour Azure Bot's Microsoft App ID — a GUID
Client SecretA secret you generate for that app registration
App TypeWhether the app is single-tenant or multi-tenant
Directory (Tenant) IDYour Microsoft Entra ID directory ID — a GUID

Create the Azure Bot resource​

  1. Sign in to the Azure portal.

  2. Select Create a resource, search for Azure Bot, and select Create.

  3. Fill in the basics:

    • Bot handle — a unique name, for example contoso-ottobot.
    • Subscription and Resource group — choose or create as you prefer.
    • Pricing tier — the free tier is sufficient to start.

  4. Under Microsoft App ID, choose Create new Microsoft App ID, then pick the app type:

    • Multi-tenant — recommended, and the default in Phoenix.
    • Single-tenant — use this if your organization's policy requires the app be limited to your directory only.
    note

    User-assigned managed identity is not supported. Phoenix needs a client secret to authenticate on your behalf, and a managed identity does not provide one.

  5. Select Review + create, then Create. Wait for the deployment to finish.

Find your App (Client) ID​

  1. Open your new Azure Bot resource.
  2. Select Configuration in the left menu.
  3. Copy the value labelled Microsoft App ID.

This is a GUID, formatted like 00000000-0000-0000-0000-000000000000. This is your App (Client) ID.

Create a Client Secret​

  1. From the Azure Bot's Configuration page, select Manage next to Microsoft App ID. This opens the app registration.
  2. Select Certificates & secrets in the left menu.
  3. Under Client secrets, select New client secret.
  4. Add a description (for example, Phoenix OttoBot) and choose an expiry period.
  5. Select Add.
  6. Copy the Value column immediately.
caution

The secret Value is shown only once. If you navigate away before copying it, delete the secret and create a new one. Do not copy the Secret ID — that is a different value and will not work.

Find your Directory (Tenant) ID​

  1. In the Azure portal, search for and open Microsoft Entra ID.
  2. On the Overview page, copy the Tenant ID.

This is also a GUID. This is your Directory (Tenant) ID.

note

Each Microsoft Teams tenant can be connected to one Phoenix organization at a time. If someone else in your company has already connected this same directory, Phoenix will tell you the Directory (Tenant) ID is already claimed — see Troubleshooting.

Enable the Teams channel​

  1. Return to your Azure Bot resource.
  2. Select Channels in the left menu.
  3. Select Microsoft Teams, accept the terms, and select Apply.

Configure in Phoenix​

  1. In Phoenix, navigate to Integrations in your organization's settings.
  2. Find Microsoft Teams and select Connect.
  3. Fill in the four fields:
FieldValue
App (Client) IDThe Microsoft App ID GUID from your Azure Bot's Configuration page
Client SecretThe secret Value from Certificates & secrets
App TypeMulti-tenant or Single-tenant — must match what you chose when creating the bot
Directory (Tenant) IDThe Tenant ID GUID from Microsoft Entra ID → Overview
  1. Select Configure Integration.

Your credentials are stored encrypted at rest. When you reopen the dialog to make a change, the Client Secret field appears blank — that is expected; re-enter it to update it.

OttoBot begins serving your Teams tenant within a few minutes.

Rotating the Client Secret​

Client secrets expire. To rotate before expiry:

  1. In the Azure portal, open your app registration's Certificates & secrets.
  2. Create a new client secret and copy its Value.
  3. In Phoenix, open the Microsoft Teams integration, select Edit, and enter the new secret.
  4. Once OttoBot is responding normally, delete the old secret in Azure.

Phoenix detects the change automatically and refreshes the connection on its next cycle — no restart or support ticket needed.

Disconnecting​

To remove the Microsoft Teams integration for your organization, open the integration in Phoenix and select Remove. OttoBot stops serving your Teams tenant on its next refresh cycle. Your Azure Bot resource is unaffected; delete it separately in Azure if you no longer need it.

Troubleshooting​

SymptomLikely causeSolution
"Check: microsoftAppId"The App (Client) ID is not a valid GUIDCopy the Microsoft App ID from the Azure Bot's Configuration page. Do not paste the bot handle or resource name
"Check: aadTenantId"The Directory (Tenant) ID is missing or not a valid GUIDCopy the Tenant ID from Microsoft Entra ID → Overview. It is required even for multi-tenant apps
"Check: microsoftAppPassword"The Client Secret is blank or whitespaceRe-copy the secret Value (not the Secret ID) from Certificates & secrets
"Check: appType"An unexpected App Type valueSelect Multi-tenant or Single-tenant from the dropdown
"This Directory (Tenant) ID is already claimed by another organization"This Microsoft directory is already connected to a different Phoenix organizationA directory can only serve one organization at a time. Confirm whether a colleague already connected it, or contact support if you believe this is an error
OttoBot does not respond in TeamsThe Teams channel is not enabled, or the app was never installed in TeamsConfirm Channels → Microsoft Teams is enabled on the Azure Bot, and that the app is installed in your Teams tenant
Worked before, now silentThe Client Secret expiredRotate the secret (see Rotating the Client Secret)

Next Steps​