Skip to main content

Microsoft Teams personal tab

Overview​

The personal tab is a full-page chat app your employees open from the Microsoft Teams side bar. They chat with your AI agent, find their past conversations listed beside the chat, and save the ones they want to keep. Teams signs them in with their work account, so there is no login page.

The personal tab uses the Microsoft app of your existing MS Teams connection. Setting it up takes three steps, usually done by three people:

StepWhoWhere
1. Turn on the chat pageWhoever manages your AI agentYellow.ai platform
2. Let Teams sign people inAn Azure admin, such as an Application AdministratorAzure portal
3. Add the app for everyoneA Teams Administrator or Global AdministratorTeams admin center
note

Steps 2 and 3 can happen in either order, but nobody can sign in until step 2 is done.

Step 1: Turn on the chat page​

  1. On the left navigation bar, click Extensions.
  2. Click Channels > Messaging > MS Teams, and click Edit on your connection.
  3. Switch on Turn on the chat page.
  4. In Organisations allowed in, enter your organisation's Directory (tenant) ID. You can find it in the Azure portal under Microsoft Entra ID > Overview > Tenant ID. Only people signed in to these organisations can open the chat page.
  5. Optionally, set what people see:
    • Welcome heading. This is also the app's name in Teams, so keep it short, like "HR Assistant".
    • Welcome message.
    • Suggested questions, up to six shortcuts on the welcome screen.
    • Logo and Brand colour.
    • Note under every answer and Messages shown while the agent is thinking.
  6. Click Save.

The connection's page now shows two extra rows:

  • Teams app file. Click Download to get the .zip file you upload to Teams in step 3. Don't unzip it.
  • Application ID URI for Azure. Click Copy. You paste it in step 2.
tip

Welcome text, suggested questions, logo and colours update the next time someone opens the chat page, with no new app file. Download a new app file only to change the app's name or accent colour in Teams.

Step 2: Let Teams sign people in​

In the Azure portal, search for App registrations and open the app whose Application (client) ID matches your MS Teams connection's Client ID.

  1. Open Manifest. Find requestedAccessTokenVersion, set it to 2, and click Save. Microsoft's Teams sign-in guide asks for this.
  2. Open Expose an API. Next to Application ID URI, click Add, paste the value you copied in step 1, and click Save. It must match exactly. If Azure answers Values of IdentifierUris property must use a verified domain of the organization, follow If Azure refuses the address below, then come back here.
  3. Click Add a scope and fill it in:
    • Scope name: access_as_user
    • Who can consent?: Admins and users
    • Admin consent display name and User consent display name: for example, Sign in to the assistant
    • Admin consent description and User consent description: for example, Lets Microsoft Teams sign people in to the assistant with their work account.
    • State: Enabled
  4. Click Add a client application and add each of these IDs, ticking access_as_user each time:
    • 1fec8e78-bce4-4aaf-ab1b-5451cc387264: Teams desktop and mobile apps
    • 5e3ce6c0-2b1f-4285-8d4b-75ee78787346: Teams on the web
  5. Open API permissions. Check that Microsoft Graph > User.Read is listed, then click Grant admin consent for your organisation.

These settings let Teams hand the chat page a sign-in pass for the person using it, without a pop-up. The pass is only issued for the address in the Application ID URI, which stops other websites from posing as your assistant.

If Azure refuses the address​

Your organisation's Azure has a security rule that only accepts sign-in addresses on domains it owns, and the chat page's address is on Yellow.ai's domain, which no other organisation can verify. Microsoft's answer for this case is an exemption for this one app: it lets this app, and nothing else, use an address on another domain. A Global Administrator runs it once, on their own computer:

  1. Install PowerShell 7 (Windows PowerShell 5.1 does not work) and the Microsoft Graph module: 
    Install-Module Microsoft.Graph -Scope CurrentUser
  2. Download Microsoft's scripts from github.com/microsoft/entra-apps-identifier-uri-protection (Code > Download ZIP), unzip them, and open PowerShell 7 in that folder.
  3. Confirm the rule is what is blocking you: 
    ./CheckIdentifierUriProtectionState.ps1
    It signs you in and prints whether the protection is on.
  4. Exempt the app, using the Client ID from your MS Teams connection: 
    ./GrantAppExemption -AppId <Client ID>
  5. Go back to Expose an API and add the Application ID URI again. It now saves.

The exemption applies to this app only. A second MS Teams connection with its own app needs its own exemption. Microsoft also offers a script that turns the rule off for the whole organisation; that is not needed here, and Microsoft advises against it.

Step 3: Add the app for everyone​

In the Teams admin center:

  1. Go to Teams apps > Manage apps > Actions > Org-wide app settings. Under Custom apps, make sure people can use custom apps, then click Save.
  2. Go to Teams apps > Manage apps, click Upload new app > Upload, and choose the .zip file from step 1.
  3. Open the app, then go to Users and groups > Availability > Edit availability. Set Available to to Everyone, or choose users or groups, and click Apply.
  4. On the same page, go to Users and groups > Installs > Install app, and install it for everyone or the groups you want.
  5. Optionally, pin it: go to Teams apps > Setup policies > Global (Org-wide default) > Pinned apps > Add apps, add the app, and click Save.

Teams usually shows these changes within a few hours. Microsoft says it can take up to 24 hours.

note

If the app page has no Users and groups tab, your organisation still uses app permission policies. Allow the app under Teams apps > Permission policies > Global (Org-wide default) instead of step 3.

What employees see​

  • The app is in the Teams side bar, or under Apps > Built for your org. It works in Teams on the web, desktop and mobile.
  • New Chat starts a fresh conversation. Past conversations are listed on the right with a search box, and the bookmark icon keeps a conversation under Saved.
  • While the agent works, a short status line shows, then the answer appears word by word. Under each answer they can copy it or run a web search for their question.
  • When the chat is handed to a live agent in Inbox, a line marks where the agent joined, the agent's name shows on their messages, and name is typing shows while they type. Another line marks when the chat is handed back.
  • The sun and moon button switches between light and dark.

Update the app​

Download a new app file from the connection's page. In the Teams admin center, open the app and click Upload file. Who can use it, installs and pins stay as they were.

Keep the same Client ID and the same Yellow.ai address. If either changes, the app's sign-in details change and each person has to click Update in Teams.

Troubleshooting​

What people seeWhat to check
We couldn't sign you in. Ask your administrator to check the app's sign-in permissions, then reopen this tab.Step 2: the Application ID URI must match the connection's page exactly, both client applications must have access_as_user, and admin consent must be granted. Then fully quit and reopen Teams.
Your sign-in wasn't accepted for this assistant. Your administrator may need to allow your organisation.Organisations allowed in must contain your Directory (tenant) ID.
Chat isn't switched on for this assistant yet.Turn on the chat page is off for this connection.
The app isn't in TeamsWait up to 24 hours. Check that custom apps are allowed and that the app is available to that person.
Azure refuses the Application ID URI: must use a verified domain of the organizationYour organisation's policy blocks addresses on other domains. A Global Administrator grants this app an exemption: see If Azure refuses the address.

References​

  1. Register a tab app with Microsoft Entra ID (Teams sign-in setup, including the token version): https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/authentication/tab-sso-register-aad
  2. Restrictions on identifier URIs of Microsoft Entra applications (why Azure refuses addresses on other domains): https://learn.microsoft.com/en-us/entra/identity-platform/identifier-uri-restrictions
  3. Grant an app an exemption from the identifier URI policy: https://aka.ms/identifier-uri-protection-grant-exemptions
  4. Manage custom apps in the Teams admin center (uploading the app file): https://learn.microsoft.com/en-us/microsoftteams/teams-custom-app-policies-and-settings
Last updated on