A guide covering the configuration and use of the Microsoft Teams integration.
Related Articles:
- Webhooks
Related Guides
- Embedding your Halo Self Service Portal into Microsoft Teams
- Embedding your Halo Self Service Portal into Microsoft Teams with SSO
- Pushing the Teams Embedded Self Service Portal to Customers Microsoft Teams Tenants
- Call Pop-Up for Microsoft Teams
- Microsoft TeamsBot
The Microsoft Teams Integration that uses the new Workflow Method, will be available for customers on v2.160 and above. Apologies for any inconvenience this may cause.
Microsoft's Adaptive cards handle text blocks differently. If you were previously formatting your notification with html, it will no longer display correctly. However, the new microsoft teams Workflow method supports markdown. You can change the notification template to be formatted in markdown instead.
Main Configuration
To enable the Microsoft Teams integration, go to Configuration > Integrations, and enable the module using the plus icon in the top right hand corner of the Microsoft Teams menu icon. Once the module has been enabled, click the menu icon to begin configuring it.
This integration allows you to post notifications to channels in Microsoft Teams, just like you would send notifications via email to your technicians.
The first configuration step requires setting up a workflow for a Channel in Microsoft Teams. To do this, find a channel you'd like to send notifications to, hover over the three dots and select "Workflows":
On the Workflows screen, look for "Post to a channel when a webhook request is received".
Once you have found the option, click on it and choose a sensible name for your workflow and click Next, confirm the channel details and create the workflow. This will generate you a new URL for your workflow.
Take a copy of the unique webhook URL present in the dialog and select Done, and then head back to the Microsoft Teams module in your Halo application.
The next step is configure an outgoing webhook in Halo. Within the Microsoft Teams module there are three buttons. The first two buttons allow you to view all of your current Webhooks that you have created, and the second one takes you straight to the Webhook creation screen.
Clicking create Webhook will default the Webhook Type of the new Webhook to "Microsoft Teams Webhook". This option is essential, otherwise the notification will fail to post to Teams. The URL obtained from the Teams Workflow in the earlier step should be copied into the Payload URL field. The configuration of the Webhook events is not covered in this guide.
At this stage, there may be an error encountered around the attachment endpoint in Halo not being added to the payload sent to MS Teams. If this is the case you will need to try selecting a different output for the workflow in MS Teams:
When the Webhook is triggered, the server program running in the background will send the notification to your Teams channel. A button will be available allowing you to easily open that ticket in your Agent web application in a new browser tab.
The details part of the notification can be customised to include specific information from the ticket that you're being notified about, the same way that this information gets added to emails. To do this, click the View Templates button in the Microsoft Teams module.
Choose the template that corresponds to your Webhooks events, and customize the details for that template.
If you want an action to appear on a ticket when you call a User via the Teams Integration, you can check the option in the tab shown below on the integration page. If you are using opportunity tickets, you can also have the call button for microsoft teams appear under the email address of the user on the opportunity.
Direct Messaging
You can also message a user and leave an action on the ticket, this is configurable in the "Direct Messaging" tab.
Agent Bot
The tab for configuring a microsoft teams bot has a seperate guide: Microsoft Teams Bot.
End-User Chat
End-user chat can be enabled in Microsoft Teams so that end-users can communicate with a chatbot that sits in Microsoft Teams based on a chat profile that you have created.
The chat profile you choose must allow access to anyone (must not be restricted to authenticated users only).
It is possible to add your own branding to the chatbot, as well as personalize the welcome message that is sent to an end-user when they install the app in Microsoft Teams from your organization's app library. In addition to this, you can also modify the help command's text, allowing you to personalize the chatbot's instructions as well as include other contact information that may be useful to the user if they don't get the response they need from the chatbot.
To add your own branding to the chatbot, you can use the manifest generator (click the Create Manifest button). This will allow you to add two descriptions and two logos that will be used for the chatbot in Microsoft Teams and visible to your end users.
Saving this input screen will download a manifest.zip file. This zip file can be manually installed into Microsoft Teams for personal use, or for your entire organization. To install the app, open Microsoft Teams and navigate to Apps > Manage your apps > Upload an app and select your desired option. You will then be prompted to select your manifest.zip file. Please note that Microsoft Teams will reject any naming variation of this folder, so the name must be exactly manifest.zip.
Once selected, you will be prompted to install the app.
After installation of the app is successful, the chatbot will send you the configured welcome message. If, for whatever reason, the chatbot is not successful in recognising your Halo instance, a default welcome message will be displayed.
There are three bot commands available to the user: the help command, Start a new conversation, or End the conversation.
Once a new conversation is started, the user can begin conversing with the chatbot following the chat profile you have created.
The user can end the conversation at any point by using the End the conversation command.
All current chat profile functionality is supported in the Microsoft Teams chatbot, including speaking to an agent via live chat. In the above chat, if the user selects I'd like to speak to someone, the chatbot will attempt to connect them to an available agent. The agent can then communicate to the user in Microsoft Teams through the chatbot using live chat in Halo.
Chat Management
To enable chat management, navigate to the tab on the microsoft teams integration module and enable "Enable chat management and messaging chats from HaloPSA"
The application requires a mixture of delegate and application permissions. The application type permissions are required to create subscriptions via the Microsoft Graph API for chats that are created.
The option to enable the ability to see and create new chats is then turned on at Ticket Type level. There is also an option to specify a default name for new chats that will auto-populate on the creation screen, which overrides the global setting found in the integration setup screen.
There are two ways of managing Microsoft Teams chats from within a Ticket.
Ticket Tabs
To enable this functionality, you must enable the following setting at Ticket Type level. Whenever a chat is created, a new individual tab will display on the Ticket for each chat.
To create the chat from within a Ticket, hover over the quick action menu and select the Create Microsoft Teams Chat option. Note that this option will be available on the Ticket regardless of whether the above setting is enabled.
This will display an input screen where you can configure your new chat.
The user who authorized the integration will be automatically added as an owner of the chat during the creation. Only user(s) imported via the Azure Active Directory integration can be added as a member.
Once the chat is created, a new tab will display on the Ticket. As part of the chat creation, a subscription to the chat will be created so that any new messages added to the chat from within Microsoft Teams will be automatically imported.
Using the plus icon in the top right hand corner, new messages can be sent to the chat from Halo. Any message sent from Halo will show in the message list as being sent by the user who authorized the integration, but a sub header showing the agent who performed the action is also shown for auditability.
Custom Dashboards
A new widget type called Microsoft Teams Chats can be added to a custom Ticket dashboard.
The widget will display all chats created from the Ticket in separate tabs, but all within the widget. A new chat can be created when viewing the widget by clicking the plus tab option. The functionality within the widget is identical to the Ticket Tabs method. To configure ticket dashboards, check out this guide: Ticket Dashboards
A background service will renew any chat subscriptions that are close to expiry on open Tickets. Once a Ticket is closed, the subscription will no longer be renewed and new messages will no longer be imported from Microsoft Teams.
Enabling Presence Notifications
The following pre-requisites must be met to use this functionality:
- The scheduling service must be enabled.
- The Microsoft Teams integration must be enabled.
- The Microsoft Entra ID integration must be enabled and you must be using it to import at least one agent.
The functionality must first be enabled in the Microsoft Teams integration on the Presence Notifications tab.
Once enabled, presence rules can be defined that allow you to determine what a technician's status should be updated to based on the Availability and Activity properties of the Microsoft Teams presence. There is also an option to only apply a rule if the technician is currently online in Halo (requires online presence functionality to be enabled in Halo first).
After configuring the integration at the Microsoft Teams level, additional configuration is required at the Microsoft Entra ID level. The Presence.Read.All (delegated) permission must be added to the Azure app and the option to allow imported agents to use the functionality must be enabled. Note that agents will not be able to subscribe to the notifications until they have been reimported either via the Halo Integrator or manually in the agent web application.
Once all configuration steps have been completed, agents can then subscribe to presence notifications individually on the Integrations tab of their profile.
Subscriptions will be renewed automatically when they are due to expire in the next 20 minutes, either during the processing of a new presence notification or via the task scheduler. After receiving and processing the notification, there may be a short delay before the agent's status change is reflected in the top right corner of the application.
Importing Shifts from Teams
If you are using the shifts functionality in Halo you can import your shifts from teams into Halo. Shifts in teams will need to be assigned to a user before they can be imported. The shifts will then be assigned to the respective agent in Halo when imported but the agent must be synced with Microsoft Entra ID and have the setting "Enable shift imports" turned on against their account.
To enable shift imports head to configuration > integrations > Microsoft Teams > shifts tab (this tab will only appear if you have shifts enabled). For more information on shifts and enabling them see our dedicated article here. Enable the setting 'Enable shift imports', this will show the connection details. Now you will need to create an Azure application. Set the authentication method to your preferred method and set the 'Authority' field to 'Microsoft Graph Global service' (This Microsoft API is currently only supported for the Global Service Authority).
When setting up your Azure application you will need need to set the redirect URI to be "https:/YOURHALODOMAIN/authcallback" but the specific URI to use can be found on the setup page for the integration in Halo.
The Azure application will need the following Graph API permissions:
- Delegated
- Group.Read.All
- Team.ReadBasic.All
-
Application
-
Schedule.Read.All
-
Schedule.ReadWrite.All
-
Admin consent will need to be granted for some of these permissions.
Once created add the application details into the setup page in Halo and authorise the application. The additional setup will now be visible.
There are two methods in which shifts can be imported, using webhooks or the integrator.
Before you import any shifts you will need to ensure the agents that you are trying to import shifts for have shift imports enabled. To do this select the 'Enable shift imports for Agents' button on the setup screen, select the team of agents you would like to enable this for, then hit save, this will enable shift imports for all agents in this team.
Note: Agents shifts are being imported for will need to be synced with Microsoft Entra ID. This allows the user of the shift to be matched to the respective agent in Halo. If shifts are not importing for certain agents ensure these agents are syncing with Entra.
Webhooks:
When using webhooks shifts will be imported as soon as they are created, deleted or updated in teams. To create the webhooks for the import add a mapping to the 'Team Mappings; table. By adding a mapping to the table webhooks will be created to automatically import the shifts for this team when any changes are made. In the below example only the shifts for the Documentation and Infrastructure team will be imported.
Integrator:
To have shifts imported on a scheduled basis using the Halo integrator check 'Enable the Halo Integrator for the Microsoft Teams integration', this will automatically import shifts on a daily basis using the Halo integrator. You can have the integrator enabled in addition to using webhooks as additional assurance that shifts have been imported.
Teams shift groups can also be mapped to a Halo shift type, this allows teams shift groups to be imported with a specified shift type in Halo. To do this add a mapping to the shift type mappings table.
