Perceptyx Teams App Installation Guide

The Perceptyx app for Microsoft Teams sends people a chat message when there is something waiting for them in Perceptyx. It uses that chat to:

• Send survey invitations and reminders.
• Let people know when they have been asked to give 360 feedback.
• Tell people when new reports, tasks, or insights are posted to their account.
• Deliver Activate nudges and AI coaching, if your organization has Activate.

Before you install

There are two things Perceptyx has to set up on our side before the app will work for your organization:

• Create your organization's Teams account in Perceptyx, connected to your company email domain.
• Turn on Teams notifications for your organization's self-led listening events.

Choosing your installation path

There are three ways the Perceptyx app can end up in someone's Teams. Pick the one that fits how you want to roll it out. The rest of this article covers each one.

Installing it yourself

Anyone can install the Perceptyx app for themselves from the Microsoft Teams Store. It is the quickest option for a pilot or for one person. For a full rollout, your IT team will usually install it for everyone instead (see Installing it for your organization).

Step 1: Open the Perceptyx listing

1. Open the Perceptyx listing on Microsoft AppSource in your browser, or search for "Perceptyx" in the Teams app store.
2. Click Get it now.

1. If your browser asks, allow it to open Microsoft Teams.

Teams opens and shows the Perceptyx app card.

Step 2: Add the app

1. Click Add.
2. If your organization needs an administrator to approve new apps, follow the prompt to request access. Once it is approved, come back and click Add again.

Step 3: Check it worked

When the install finishes, you get a "Welcome to Perceptyx for Teams" message. That is it, there is nothing else to do. From here on you will get a message in Teams whenever your organization launches a survey or something new is waiting for you.

Installing it for your organization (Teams administrators)

A Microsoft Teams administrator can install the Perceptyx app for everyone, or just for a specific group, which is handy for pilots and phased rollouts. Microsoft is moving organizations between admin experiences, so your Teams admin center will look like one of these three:

• Modern: app-centric management. Each app has its own page, with an Edit installs action on the Users and groups tab.
• Legacy: app setup policies. Installed apps and pinned apps are two separate lists inside a setup policy. This is what older tenants that have not moved over yet will see.
• Newest: unified app management. Apps for Teams, Outlook, and Microsoft 365 Copilot are managed in one place, from either the Teams admin center or the Microsoft 365 admin center. You opt in from a banner at the top of the Manage apps page.

All three get you to the same place: Perceptyx installed for each person, in their own one-on-one chat with the app. The idea is the same whichever screens you see. Pinning makes the icon visible, installing makes the app able to reach people, and you usually want both.

Permissions the app uses

The Perceptyx app asks for these permissions:

The app does not ask for elevated permissions across your tenant, and it does not read messages in any other chat or channel. If your tenant requires admin consent before allowing custom apps, an administrator will be prompted on the first install, or can approve it from pending requests in the Teams admin center.

Allow the app in your tenant

1. Sign in to the Microsoft Teams admin center as a Teams Service Administrator or Global Administrator.
2. Go to Teams apps and then Manage apps.
3. Search for "Perceptyx" and check that its status is Allowed. If it is blocked, click the row and then click Allow in the top right.

Modern path: app-centric management

If you see an Edit installs action on each app's page, your tenant uses app-centric management. This is the simplest way to install Perceptyx for everyone or for a group.

1. In the Microsoft Teams admin center, go to Teams apps and then Manage apps.
2. Search for "Perceptyx" and click the app name to open its page.
3. Click the Users and groups tab.
4. Click Install app, or Edit installs if some people already have it.

1. In the install panel, choose who gets it:
   • Everyone to install Perceptyx for your whole organization.
   • Specific users or groups to pick a security group, distribution list, or Microsoft 365 group (for example, "Perceptyx Pilot").
2. Click Apply.
   Microsoft rolls the install out to each person's Teams over the next 1 to 6 hours.

Legacy path: app setup policies

If your tenant has not moved to app-centric management, you set up installs through app setup policies. A setup policy has two separate lists:

• Installed apps are the apps added to someone's Teams when the policy applies to them. This is the list that makes Perceptyx notifications work.
• Pinned apps are the apps that show in someone's Teams sidebar. Pinning on its own does not install anything.

1. In the Microsoft Teams admin center, go to Teams apps and then Setup policies.
2. Open the policy for the people you want to install Perceptyx for. That is usually Global (Org-wide default) for everyone, or a custom policy for a pilot group.
3. Under Installed apps, click Add apps, search for "Perceptyx", select it, and click Add. (Skip this step if there is no Installed apps section. Install Perceptyx using the Modern path above instead.)
4. Under Pinned apps, click Add apps, search for "Perceptyx", select it, and click Add. Drag it to where you want it to sit in people's sidebars.
5. Click Save at the bottom of the policy.

If you used a policy other than the global default, remember to assign it to the right people or groups under Group policy assignment in the same Setup policies area.

Newest path: unified app management

Unified app management is Microsoft's newest admin experience. It brings app management for Microsoft Teams, Outlook, and Microsoft 365 Copilot together in one place, and you can reach it from either the Teams admin center or the Microsoft 365 admin center. Whatever you set in one shows up in the other.

Your tenant can move to it when you see a banner at the top of the Manage apps page that says "Simplify how you manage apps and agents", with a Move to unified app management button on the right.

Before you move (a one-time decision)

1. Sign in to the Microsoft Teams admin center as a Global Administrator and go to Teams apps and then Manage apps.
2. Click Learn about unifying app management in the banner and read through Microsoft's notes.
3. When you are ready, click Move to unified app management in the banner.
   A dialog box titled "Introducing a new unified app management experience" opens.

1. Read the explanation, then check I have read the information and understand the effects of this change.
2. Click Move to unified app management in the dialog box.
   Microsoft applies the move. Most tenants land straight in the new screens. Some go through the settings alignment or review summary steps first.

If your tenant gets the settings alignment step, you will see a screen like this before the move finishes, asking you to line up your Teams and Microsoft 365 app settings.

Install Perceptyx with unified app management

Once you have moved, installing Perceptyx works just like the Modern path above: find the app, open its page, choose who gets it, and apply. There are two small differences:

• You can do it from the Teams admin center or from the Microsoft 365 admin center (admin.microsoft.com, then Settings, then Integrated apps). Changes show up in both.
• An install covers Teams and any other Microsoft 365 app the Perceptyx app supports. Perceptyx works in Teams only, so for now this makes no difference to you.

1. Open Manage apps from the Teams admin center or the Microsoft 365 admin center.
2. Search for "Perceptyx" and click the app name to open its page.
3. On the Users and groups tab, click Install app or Edit installs.
4. Choose Everyone or Specific users or groups.
5. Click Apply.
   Microsoft rolls the install out over the next 1 to 6 hours, the same as the other paths.

You check it worked the same way as the other paths: make sure a test person gets the "Welcome to Perceptyx for Teams" message.

Check the rollout worked

Microsoft rolls installs and policy changes out in the background, and it can take anywhere from about 15 minutes to a few hours. To check:

1. Wait at least 30 minutes after saving.
2. Pick a test person, sign in to their Teams (web or desktop), and look for Perceptyx in the sidebar.
3. Click the Perceptyx icon. The "Welcome to Perceptyx for Teams" message should be there.
4. If it has not shown up within an hour, head to Troubleshooting.
5. (Optional, administrators only) If you need a definite answer for one particular person, see Confirm an install with Microsoft Graph below.

Confirm an install with Microsoft Graph

Microsoft Graph gives you a definite answer on whether one person has the Perceptyx app installed. It is the same check Perceptyx runs when looking into a problem, so your IT team can confirm things themselves without opening a support ticket.

To check one person:

1. Open Microsoft Graph Explorer.
2. Sign in (top right) as a tenant administrator with Teams admin permissions. If you see an orange banner saying "You are currently using a sample account", you are not signed in yet.
3. Find the person's Entra Object ID. In the Microsoft Entra admin center, go to Users, search for the person, and copy their Object ID (a long string of letters and numbers, like 00000000-0000-0000-0000-000000000000).
4. Paste this into the Graph Explorer query bar, swapping {user-object-id} for the Object ID you just copied, and make sure the dropdown next to it is set to GET:
   https://graph.microsoft.com/v1.0/users/{user-object-id}/teamwork/installedApps?$expand=teamsAppDefinition
5. Click Run query.
6. Look through the response. It lists every Teams app that person has installed. The field you care about is teamsAppDefinition.displayName. Look for "Perceptyx".

If Graph Explorer does not give you what you expect

"You are currently using a sample account. Sign in to access your own data."

Graph Explorer opens in sample mode by default. Click sign in at the top right and use your tenant administrator account. The orange banner goes away and your own avatar shows up.

HTTP 403, "Forbidden", or "permission TeamsAppInstallation.ReadForUser.All required"

You are signed in, but Graph Explorer has not been given permission to read another person's installed apps yet:

1. In the response area under the query bar, click the Modify permissions tab.
2. Find TeamsAppInstallation.ReadForUser.All in the list. If your organization requires admin consent for new permissions, you may see a Consent button or a Request admin consent link.
3. Click Consent and finish the Microsoft prompt. If your account cannot give consent for the whole tenant, ask a Global Administrator to do this once. You will not need to do it again.
4. Run the query again.

HTTP 404 or "Resource not found"

This is almost always a typo in the Object ID. Double-check it in the Microsoft Entra admin center under Users. Capital letters do not matter, but the rest has to match exactly, with no extra spaces.

An empty result (the query works but lists no apps)

The person has no Teams apps installed at all, not even Microsoft's built-in ones. That points to a wider problem with their account, and it is worth raising with Microsoft support.

Sending messages through Teams

Once the app is installed, you choose whether each notification goes out through Teams. You set this per notification, not per event, so you can send the invitation by chat and a reminder by email, or any mix you like.

Self-led listening events

When you create an invitation or reminder in the Launch phase of your event, you will see two check boxes at the bottom of the notification:

• Include Chat Notification sends a Teams message as well as the email. Both go out at the same time.
• Chat Only becomes available once Include Chat Notification is checked. It stops the email, so Teams is the only way the notification is delivered.

For the full walkthrough of creating notifications, see Launch Your Listening Event.

Activate nudges and AI coaching

If your organization has Activate, nudges and coaching come through the same Perceptyx app with no extra setup beyond installing it. To start a coaching session, people just type "Hi", "Hello", or "Help" in their Perceptyx chat.

Troubleshooting

"You cannot send messages to this bot"

This is the most common problem when an administrator deploys the app. The person can see the Perceptyx icon in their sidebar, but when they click it the message box is unavailable and they see "You cannot send messages to this bot".

What it means

Perceptyx is pinned for that person, so they see the icon, but it is not installed, so the app cannot send them anything. This is a Microsoft setting rather than a Perceptyx outage. Survey invitations and coaching messages cannot reach anyone in this state.

How to fix it (a Teams administrator needs to do this)

Add Perceptyx to Installed apps as well as Pinned apps, or use Edit installs:

• Modern path: Teams admin center, then Manage apps, then Perceptyx, then Users and groups, then Install app. Choose everyone or the group that is affected.
• Legacy path: Teams admin center, then Setup policies, then the affected policy, then the Installed apps section, then Add apps, then Perceptyx, then Save.
• Newest path: Teams admin center, then Manage apps, then Perceptyx, then Users and groups, then Install app. Or Microsoft 365 admin center, then Settings, then Integrated apps, then Perceptyx, then Edit installs.

After you save, Microsoft needs 1 to 6 hours to roll it out. Once it has, the affected people get the welcome message the next time Teams refreshes, and notifications start coming through.

Microsoft's own documentation on this:

• Send proactive messages (explains why the app has to be installed, not just pinned)
• Preinstall Teams apps for your organization

Some people get notifications and others do not

A common pattern is that people who have been around a while get Perceptyx notifications fine, but newer people, or certain departments, do not. That usually means the setup policy only installed Perceptyx for the people who were there when it was first applied, or that it only pins the app. Newer people never get a real install.

The fix is the same as above: make sure Perceptyx is in Installed apps (or use Edit installs) and that the policy is assigned to everyone who should have it.

"Thanks for your interest in the Perceptyx Microsoft Teams application!"

This message means Perceptyx could not yet match the person's Teams account to their employee record. It usually happens when someone installs the app before Perceptyx has finished setting up your organization's account.

Contact your Perceptyx Customer Success Manager with the email address of the person affected. Once the setup is finished on our side, they will automatically get the normal "Welcome to Perceptyx for Teams" message and notifications will start arriving.

Someone cannot see the Perceptyx app at all

If someone cannot find Perceptyx anywhere in Teams, not in the sidebar and not in a search of their apps, check these four things in order:

1. Have they signed out of Teams and back in since the policy was applied? Microsoft does not always push changes to a Teams session that is already open. Signing out and back in forces a refresh.
2. Does their app permission policy block custom apps? In the Teams admin center, go to Permission policies and check that custom apps are allowed in the policy assigned to them.
3. Has the policy actually been applied to them? In the Teams admin center, go to Users, open the person, and check under Policies that their app setup policy is the one that includes Perceptyx.
4. For a definite answer, check Microsoft Graph. See Confirm an install with Microsoft Graph above. Whether Perceptyx shows up in the results tells you exactly whether the install finished, whatever the Teams admin center says.

Where to get help

For questions about installing the app, contact your Perceptyx Customer Success Manager. If the problem is messages not being delivered, include the email address of the person affected and roughly when you noticed it, so we can look into it on our side.

Appendix A: Quick reference

Which option to use

Appendix B: Rollout planning questionnaire

Use these questions to plan your Teams rollout. Each answer points to one of the paths in this article, so once you have worked through them, your rollout plan is mostly decided.

1. Rollout scope

Who in your organization should get Perceptyx notifications in Teams?

• ☐ Everyone in the tenant
• ☐ One specific group (group name): ____________________
• ☐ Phased, starting with a pilot group, then expanding. Pilot group: ____________________
• ☐ Self-install (people opt in themselves from the Microsoft Teams Store)

2. Installation method

How will the app get to people?

• ☐ Administrator push (recommended). IT installs it for people from the Teams admin center.
• ☐ Self-install. People install it themselves from the Teams Store.
• ☐ A mix. Administrator push for some people, self-install for others.
• ☐ Not sure yet. We will set up a follow-up with our IT team.

3. Sidebar pinning

Should the Perceptyx icon be pinned in people's Teams sidebars?

• ☐ Yes, pin it so people can find it (recommended, as well as installing it)
• ☐ No, install only. People will still get notifications without seeing the icon.

4. Admin screens

Which admin experience does your tenant use? (Your IT administrator can check by signing in to the Teams admin center.)

• ☐ App-centric management (Modern: Teams admin center, then Manage apps, then Edit installs)
• ☐ App setup policies (Legacy: Teams admin center, then Setup policies, then Installed apps and Pinned apps)
• ☐ Unified app management (Newest: managed from the Teams admin center or the Microsoft 365 admin center, after clicking the Move to unified app management banner)
• ☐ Not sure. IT will check before making the change.

5. Features

Which Perceptyx features will people have?

• ☐ Surveys and reports only
• ☐ Activate nudges
• ☐ Activate AI coaching

6. Admin consent for custom apps

Does your tenant need an administrator to approve custom apps?

• ☐ Yes. IT will approve Perceptyx ahead of time in the Teams admin center under Manage apps.
• ☐ No. Perceptyx is already allowed, or no approval is needed.
• ☐ Not sure. IT will check.

7. Email domains

List every email domain Perceptyx should connect to your Teams setup. We need these to match people's Teams accounts to their employee records. Without them, people see the "Thanks for your interest" message.

Domains (one per line, for example acme.com, acme.co.uk):
____________________________________________
____________________________________________
____________________________________________

8. Microsoft 365 tenant ID

Your Microsoft 365 tenant ID. You can find it at admin.microsoft.com, then Settings, then Org settings, then Organization profile. Or in PowerShell: Connect-MgGraph; Get-MgOrganization | Select Id.

Tenant ID: ____________________________________________

9. Existing installs

Has anyone in your organization already installed the Perceptyx app?

• ☐ No, this is a fresh rollout.
• ☐ Yes, some people have installed it themselves. IT can see how many in the Teams admin center under Manage apps, then Perceptyx, then Users and groups.
• ☐ Not sure

10. Timeline and contacts

• Target go-live date: ____________________
• Your IT or Teams administrator (name and email): ____________________
• Your Perceptyx Customer Success Manager (name and email): ____________________

Appendix C: Glossary