Microsoft Teams
Microsoft Teams Integration with XCALLY
XCALLY Motion enables you to integrate Microsoft Teams as a New Channel, using the Open Channel.
Customers can interact with your Agents, sending and receiving direct messages, from your Microsoft Teams Official Account.
Agents are able to receive the incoming messages on a special Microsoft Teams Queue and to reply from the XCALLY Motion standard GUI.
To make the Integration work, you need to configure your Microsoft Teams Account and your XCALLY Motion.
Let’s see how to configure Microsoft Teams Integration!
Requirements
XCALLY Motion version 3.0.9 or higher to run this plugin
Valid Azure Subscription
Access to a Microsoft Teams Account with Admin credentials (or MT admin collaboration)
Microsoft Teams Configuration
Bot creation
Go to http://dev.botframework.com/bots .
Click on “Create a bot”
Click on “Create”.
You will be redirected to portal.azure.com.
Scroll down until you see “Load more” in the bottom of the page.
Scroll down and click “Load more” until you see “Azure Bot” from Microsoft.
Click on “Create”.
Bot handle → write a name. No spaces allowed. Recommended to write a name a meaningful name as it can’t be changed later. This is a private name and won’t be seen by customers.
Subscription → choose a valid subscription associated to your Microsoft Account.
Resource group → choose global or a region near your business. Create a new Resource group to access more settings.
Pricing tier → Click on “Change plan” and choose “Free” tier to avoid paying for messages. The Standard price tier only guarantees about messages incoming from Microsoft Teams to XCALLY Motion.
Type of App → Choose Single Tenant when in doubt.
Creation type → Leave selected “Create new Microsoft App ID”
Click on “Review + Create”.
This will create on the Azure subscription two items, an Azure Bot and an Enterprise App with the same name.
Add a New Client Secret
Go in the related Enterprise App and go to the left menu voice “Certificates & Secrets”.
Click on “+ New client secret”.
Suggested values.
Click on the blue “Add” button.
Save the “Value”. We will need it to setup the MT plugin.
The “Value” string will be censored if you change page and there is no way to recover it, you will need to create another client secret if you lose the Value.
Add Teams Channel
Go to the Azure Bot resource in Azure Portal.
Add Microsoft Teams from the Available Channels list.
In Messaging, leave “Microsoft Teams Commercial”.
In Calling, leave blank.
Click on Apply on the bottom bar.
From the Configuration section:
Set Messaging endpoint to: https://your.public.domain/api/plugins/webhook?port=3980&path=/api/messages
Save the “Bot Type”, the “Microsoft App ID” and the “Microsoft Tenant ID”. We will need them to setup the MT plugin.
Change port and public domain to match the actual domain where it is installed XCALLY Motion V3 and the plugin port (3980 is the default port).
Click on Apply.
App creation
Go to the Microsoft Teams desktop app.
Add to Microsoft Teams an app called Developer Portal.
Go to Apps tab.
Click on “New App”, write a name. This will be the public name of the app.
Fill the form.
ID Application must be the same as the App ID of the Enterprise App in the Azure portal.
Click on the menu Capabilities.
Add Bot feature.
The bot ID must be the same as the Azure Bot app ID.
Enable file upload.
Check only “Personal” chat scope.
Go to Publish and choose Package export and download it.
User App Installation
Go to https://admin.teams.microsoft.com/
Go to Teams apps.
Click on Manage apps.
Click on “+ Upload”.
In the popup, drag and drop the zip app package made with Developer Portal or click on “Upload” to choose from file system.
WAIT A FEW HOURS BEFORE THE APP IS PUBLISHED INTO MICROSOFT TEAMS.
When the app is published it can be seen only by users in the same enterprise and it can be found in the app store of Microsoft Teams.
Every user must add the app manually to chat with it or you can make a custom user group policy where the app is already installed and then add users.
Further versions of the app must have a greather version number, example if the current is version 1.0.0, the next must be 1.0.1.
For further Microsoft Teams documentation, click here.
XCALLY Configuration
In this section you’ll see how to install and configure the XCALLY Motion Microsoft Teams Plugin interface, in order to let your Agents interact with Microsoft Teams users.
In this phase of the process, you need to access your XCALLY Motion as Admin.
Setup Microsoft Teams Account
Access the Open Channel Section:
Create a new Open Channel Account in your XCALLY Motion, clicking on the plus button and filling the fields:
Name: choose a name for your Microsoft Teams Account
Key: enter a specif key (it must different for each channel)
Reply URL: http://localhost:3980/sendMessage . This URL is going to be used by Open Channel to answer to the interactions.
List: Choose the List where the new contacts will be saved in the Contacts Manager. If a contact is already present in the List, the new interaction will be associated and reported in the Customer Journey.
Description: (Optional) Describe to which bot the channel is associate.
To configure the Microsoft Teams Account:
Select the Microsoft Teams Account in the list of Openchannel Accounts, click on the button and Edit it:
Check the information and complete the Microsoft Teams Account configuration:
On the top of the screen, you can see the ID Account (the number that follows the # ).
Save the ID Account Openchannel. We’ll need it to setup the Telegram plugin.
Setup Microsoft Teams Queue
In order to have Agents receive notifications from the Microsoft Teams Account and manage interactions, you need to configure a specific Queue.
Follow the next steps:
Create a new Open Channel Queue, as Microsoft Teams Queue.
Add Agents or Teams to the Microsoft Teams Queue.
Associate he Microsoft Teams Queue to the Microsoft Teams Account.
Please refer to this documentation to complete this phase of the process.
Generate API Key
Plug-ins, as Microsoft Teams, are connected to XCALLY Motion through the API Key.
To generate the API Key, go to the Staff section and open the User section
Select your Admin user and press on the three dots button to Edit it:
Click on the API Key Manager Icon:
Generate the API KEY, clicking on GENERATE button:
Save the API Key. We will need it to setup the Microsoft Teams plugin.
Upload the Plugin to XCALLY Motion
It is necessary to upload the plugin.
Download the Microsoft Teams Plugin zip file: https://repository.xenialab.com/repository/plugins/teams-plugin/teams-plugin-v2.0.0.zip
Open the App Zone section
Upload the Microsoft Teams Plugin:
After the upload, you will find it in the list of the uploaded App Zone Plugins:
To Install the plugin, click on button, and click Install plugin:
Click on the button to edit the plugin. Select in the Sidebar field how/to whom this integration must be shown in the menu (default value: Admin Only)
Now your Microsoft Teams Plugin is active!
XCALLY Motion does not support two or more identical plugins, concurrently active. For more information, please contact us via Support Portal.
Setup Microsoft Teams Plugin
To configure the Plugin for Microsoft Teams, access the Plugins section and select Microsoft Teams Openchannel.
Fill and check the fields:
Webhook (XCALLY Motion Omnichannel): http://localhost:9000/api/openchannel/accounts/ID-CHANNEL/notify , where the 'ID_CHANNEL' is the Openchannel Account ID previously saved.
API Key (Admin): Insert the API Key previously saved
Port: Plugin port (choose a different port for each plugin)
URL (public) XCALLY Motion: Enter the public XCALLY Motion URL
Proxy token: If necessary, insert the proxy token.
Teams
Microsoft app ID: Insert the Microsoft app ID previously saved
Microsoft app password: Insert the Microsoft app password (Value) previously saved
Microsoft tenant ID: Insert the Microsoft tenant ID previously saved
Microsoft app type: Insert the Microsoft app type (Bot Type)previously saved
Unsupported type of message text: Message that appears to your Customers in case of unsupported message
File to big: Message that appears to your Agents in case the attachment sent by the Customer is too big for Motion to handle
Remember to Restart the Plugin:
Go to the App Zone section, select the Microsoft Teams plugin
click on the button and choose the Restart plugin command:
Microsoft Teams Integration is ready to be used!
Microsoft Teams Interactions
The Microsoft Teams interaction below shows the communication between the Microsoft Teams user and your Agent (who interacts from the XCALLY Omnidesktop Interface.
Note that:
Motion supports attachments up to 15 MB.
Text or attachments can be exchanged: they must be sent in different messages.
Additional Information
Debugging/Troubleshooting
All of the log files for Microsoft Teams plugin events are available at /var/log/xcally/ directory under openchannel-teams- naming convention.
Place a reminder every 2 years to change the Secret ID and Secret Value of the Enterprise App in the Azure Portal.
Change the messaging endpoint in the Azure Bot if you moved XCALLY Motion server instance to another domain.