> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Microsoft Teams tenant
> Connect a Microsoft 365 tenant to your organization: prerequisites, the permissions granted, uploading the app package, connecting the tenant, team installs for channel routing, and removal. Everything on this page is an administrator's step.
Two Microsoft roles take part: a Teams Administrator uploads the app package, and a Global Administrator connects the tenant. Once the tenant is connected, members chat with Omni, the built-in agent, and agent owners route team channels from the agent's settings; that side is on [Agents in Microsoft Teams](/guides/deploy/microsoft-teams).
## Prerequisites
* **Custom app upload permitted.** xpander is distributed as an app package (`.zip`) rather than through the Teams store. Confirm custom app upload is allowed under **Teams admin center → Teams apps → Manage apps → Org-wide app settings**. If your policy blocks it, contact xpander before continuing.
* **A Global Administrator.** Connecting a tenant grants a tenant-wide Microsoft Graph permission. Only Global Administrator or Privileged Role Administrator can approve it. Assignments are listed under **Microsoft Entra admin center → Roles and administrators**.
* **A Teams Administrator** to upload the package.
* **An xpander organization** in which you hold the admin role.
Supply your xpander contact with your **tenant ID**, shown in the Microsoft Entra admin center under **Overview**.
## Permissions
xpander requests the following permissions, granted at different points during setup.
| Permission | Type | Scope | Granted during |
| --------------------------- | ------------------------------- | ---------------------------------- | --------------------------------- |
| `Channel.ReadBasic.All` | Microsoft Graph, application | Channel names and IDs, tenant-wide | Step 2, by a Global Administrator |
| `ChannelMessage.Read.Group` | Resource-specific consent (RSC) | Messages within one team | Step 4, by that team's owner |
`Channel.ReadBasic.All` returns channel names and IDs. It does not provide access to message content, mail, files, or calendars.
`ChannelMessage.Read.Group` is granted per team when the app is installed to that team. Teams without the app installed are not readable.
xpander stores no Microsoft access token or refresh token for your tenant. The connection is a record associating your tenant ID with your xpander organization.
Users are identified by the work email address Microsoft supplies with each message. Each user has their own conversations with Omni and their own history.
Application (client) ID: `6ef090b1-c159-4fbf-9011-fc9db88fc91a`
## Step 1: Upload the app package
**Role required:** Teams Administrator
1. Obtain the app package (`.zip`) from your xpander contact.
2. In the [Teams admin center](https://admin.teams.microsoft.com), go to **Teams apps → Manage apps**.
3. Select **Actions → Upload new app** and choose the package.
4. Confirm the app status is **Allowed**.
5. Verify your app permission and setup policies allow users to run it.
Without admin center access, enable **Upload custom apps** in your Teams setup policy, or upload from the Teams client under **Apps → Manage your apps → Upload a custom app**.
Custom-uploaded apps do not appear in Teams store search. To make xpander discoverable, publish it to your org catalog, where users find it under **Apps → Built for your org**. You can also pin it through a setup policy.
## Step 2: Connect your tenant
**Role required:** Global Administrator, who must also be an xpander organization admin
1. In Xpander Chat, go to **Settings → Channels**.
2. Select **Connect Microsoft Teams**.
3. Sign in with your Microsoft administrator account.
4. Review and accept the consent prompt.
The Channels tab then lists your tenant as connected. Its Microsoft Teams switch turns the channel on or off for the whole organization, and a change lands in **Settings > Audit logs** as `Org Channels Updated`.
Each Microsoft tenant maps to one xpander organization. Connecting a second tenant replaces the existing mapping.
Signing in without Global Administrator rights fails with a message stating that an administrator is required, and no connection is created. Repeat the step using an account that holds the role.
If the connection succeeds but channel lists are empty in Step 4, the tenant-wide grant did not complete. A Global Administrator can grant it directly:
```
https://login.microsoftonline.com/{tenant-id}/adminconsent?client_id=6ef090b1-c159-4fbf-9011-fc9db88fc91a
```
Replace `{tenant-id}` with your tenant ID. Confirm the outcome in the Microsoft Entra admin center under the application's **API permissions**, where the permission status shows as granted for your organization.
## Step 3: User access
No administrator action is required.
Users open xpander in Teams and send a message. Accounts link automatically when the Microsoft work email matches an existing xpander account. Otherwise the user selects **Link account** and signs in once.
## Step 4: Enable channel routing (optional)
**Role required:** team owner, for each team
Complete this step only for teams where an agent should respond to messages that do not mention it directly.
1. In Teams, open the team.
2. Select **••• → Manage team → Apps → Add**.
3. Add the xpander Teams app.
4. Accept the consent prompt referencing receipt of channel messages.
Adding the app as a channel tab or as a personal app does not enable routing. Only a team-scope install grants `ChannelMessage.Read.Group`. The consent prompt referencing channel messages confirms the install type is correct.
Routing itself is configured in Xpander Chat, in the settings of the agent that will answer.
## Verify the deployment
* **Settings → Channels** in xpander lists your tenant as connected.
* A direct message to the app in Teams returns a reply.
* After Step 4, the channel picker in an agent's settings lists your teams' channels.
## Troubleshooting
The signed-in account lacks the Teams Administrator or Global Administrator role. Assign the role, have an existing administrator upload the package, or enable **Upload custom apps** in your Teams setup policy and upload from the Teams client.
Tenant-wide consent requires Global Administrator or Privileged Role Administrator. Application Administrator is not sufficient for Microsoft Graph application permissions. No connection was created, so the step can be repeated by an account holding the role.
`Channel.ReadBasic.All` was not granted. Use the consent URL in Step 2, then confirm the status in the Microsoft Entra admin center. Allow up to one hour for a new grant to take effect.
The app was installed as a personal app or channel tab rather than to the team. Re-add it through **Manage team → Apps** and accept the consent prompt referencing channel messages. Direct mentions work regardless of install type, so responses to mentions but not to other messages indicate this cause.
## Remove xpander
1. Disconnect the tenant in Xpander Chat under **Settings → Channels**. Routing configuration is retained and restored if the same tenant is reconnected.
2. Uninstall the app in the Teams admin center under **Manage apps**.
3. Remove the enterprise application in the Microsoft Entra admin center to revoke the Graph permission.
## Related
What members do once the tenant is connected, and their troubleshooting
The same connection for a Slack workspace