Use this guide to deploy the Cirrus Halo app from the Microsoft Teams admin centre. You will upload the approved app package, install it for your end users and pin it in their Teams app bar. Users then open the app and complete authentication. They do not need to upload or install the package themselves.

For a deployment to every user in your organisation, select the option for all users when assigning installation. If Halo is only used by your contact centre, select a group containing all intended Halo users instead.

Before you start

• Obtain the current Cirrus Halo Teams app ZIP package for your Halo environment. Keep the package intact and confirm its name and version with Cirrus.
• Use a Microsoft account with the Teams Administrator or Global Administrator role. If the app needs organisation consent through Teams admin centre, arrange for a Global Administrator to grant it.
• Ask Cirrus to confirm that your Halo environment is ready for the Teams app, including single sign-on (SSO), the Microsoft identity connection and routing to the correct Halo environment.
• Ask your Halo administrator to confirm that each intended agent has a Microsoft-linked Halo user account, the agent role and the required Agent Groups. Separate Halo password accounts cannot replace the Microsoft identity used by this app.
• Where Teams will carry calls, confirm the Teams telephony licensing and voice connection with Cirrus. App deployment does not configure the voice service.

Upload the app package

1. Sign in to https://admin.teams.microsoft.com.
2. Open Teams apps > Manage apps.
3. Select Upload new app, or Actions > Upload new app, depending on your screen. Choose the ZIP provided by Cirrus and complete the upload.
4. Open the uploaded app’s details. Confirm the name and version. Check that the app is allowed for use under your organisation’s app controls. Allow a few hours for the uploaded app to appear in the organisation’s catalogue.

Review app permissions

Open the app’s Permissions tab, or select View details in the Permissions column. Review any requested access. If organisation consent is required through this screen, a Global Administrator reviews the permissions and selects Accept. Contact Cirrus if you need clarification on the requested permissions.

Install Halo for all intended users

Publishing the app in the catalogue makes it discoverable. Central installation adds it to users’ Teams clients. Pinning provides a visible shortcut. Complete installation using the route supported by your tenant, then configure pinning on the next page.

Route A: using app-centric management

Use this route when Manage apps provides installation controls for the app.

1. Open Teams apps > Manage apps and select Cirrus Halo.
2. Select Edit installs. Alternatively, open the app details and select Users and groups > Installs > Install app.
3. Choose all users for an organisation-wide deployment, or select the group containing all intended Halo users.
4. Select Apply. This installs the app for the selected audience and makes it available to them.

Check the selected installation audience. Configuring Availability alone lets users access an app but does not complete central installation. If you need to review access, use Users and groups > Availability > Edit availability. Select Everyone for all organisation users, or Specific users or groups for a restricted audience.

If installation is unavailable for the supplied package, ask Cirrus to confirm that it supports administrator installation in personal scope. Microsoft cannot preinstall apps that lack the required scopes.

Route B: using an app setup policy

Use this route only if your tenant still allows additions under Installed apps in setup policies. Where that section is read-only, use Route A.

1. Open Teams apps > Setup policies.
2. For every organisation user, edit Global (Org-wide default). For a specific Halo audience, create or edit a custom policy.
3. Under Installed apps, select Add apps. Find Cirrus Halo, select Add and save.
4. For a custom policy, assign it to all intended users. Check their effective policy, including any existing custom assignments that take precedence over Global. Confirm the app is permitted for the selected audience.

Use personal installation for the Halo agent app. Add to team distributes apps that support a team scope and does not replace installation for each end user.

End user installation settings

End users do not need permission to upload custom apps for this deployment. The Microsoft administrator uploads the package and controls installation. Keep the organisation’s normal user upload restrictions in place.

Pin Halo and validate the deployment

Add Halo to the Teams app bar

Configure pinning through an app setup policy, including when Route A handles installation. Apply the policy to the same audience selected for installation.

1. Open Teams apps > Setup policies.
2. Edit Global (Org-wide default) for the organisation’s default app bar, or create or edit a custom policy for all intended Halo users.
3. Under Pinned apps, select Add apps. Find Cirrus Halo and select Add.
4. Set its position in the app bar and select Save.
5. Assign any custom policy to the intended users. Check Users > Manage users to verify their effective setup policy. Only one setup policy is effective for each user, so retain the other shortcuts that the audience needs.

Users with a different effective setup policy may not receive a change to Global. Update the policy that applies to them or assign the intended Halo policy. Confirm this for representative users before considering the deployment complete.

Allow settings to apply

Upload and setup policy changes can take a few hours to appear. App availability changes can take up to 24 hours, with rare cases taking longer. Allow time for the settings to reach Teams before investigating a missing app.

Check the result with representative users

Deploy centrally to a small test audience first using the same installation and pinning steps. Once the checks below pass, extend the deployment to all intended users. No user uploads are needed during testing.

1. Halo appears in Teams and is pinned in the app bar after the policies apply.
2. The user can open Halo and authenticate using their own Microsoft work identity.
3. The session opens the correct Halo environment and agent account.
4. The agent has the correct Agent Groups and can receive a test interaction.
5. Where Teams voice is configured, inbound and outbound test calls work as required and audio works in both directions.
6. The app remains accessible after Teams is reopened. Check the Teams desktop client and browser if both will be used.

What users need to do

Tell users where Halo will appear and when deployment is expected. Once the app appears, they open it and complete any Microsoft authentication prompt. Sign in uses their own identity. If browser authentication is blocked, allow the authentication pop-up for the Teams site and reopen Halo.

Troubleshoot and maintain the deployment

Halo does not appear

Check the package upload, the app’s access settings and the selected installation audience. Confirm that the affected user belongs to the assigned group. Check the effective setup policy for pinning and allow time for settings to apply. Availability, installation and pinning each need to be checked.

Halo opens, but authentication fails

Confirm the user is signed into Teams with the expected work account. Ask the Halo administrator to check the Microsoft linked user and agent role. If a browser authentication window does not open, check for a blocked pop-up. Contact Cirrus if the app opens an error page, reaches the wrong Halo environment or repeatedly fails to authenticate.

The agent signs in but cannot handle calls

Ask the Halo administrator to check active Agent Groups and routing. Where calls should use Teams, confirm the user’s Teams voice service and the Halo voice connection with Cirrus. If the app unexpectedly requests a phone number, ask Cirrus to check the identity and telephony configuration before changing the user’s settings.

Update the app

Obtain the new package from Cirrus. Open the existing app’s details in Teams admin centre and select Upload file to upload the new version. Existing policies continue to apply. Validate authentication and call handling with representative users after the update. [1]

Contact Cirrus Support

Provide the customer and Halo environment, affected Microsoft user, app package name and version, exact error, timestamp with time zone, Teams web or desktop version and whether other users are affected. Include a screenshot of the issue with unrelated employee details removed.