Webex App as a Channel

This guide demonstrates how to leverage the Microsoft Teams App as a Channel within Webex Connect. We cover the scenario of facilitating conversations between an agent, using the MS Teams App, and a customer, using a digital channel such as WhatsApp and SMS/MMS.

We will see how to:

• Initiate conversations from the MS Teams App to WhatsApp/SMS/MMS, and vice-versa
• Consume and route text based messages between each channel
• Consume and route message attachments from WhatsApp to MS Teams
• Detect agent presence
• Manage contact and session information

Prerequisites

This guide assumes that you have:

• A working knowledge of Webex Connect and the MS Teams platform.
• Familiarity with, and access to, a digital communication channel, such as WhatsApp.
• Access to, or the knowledge to develop, a web based application which can perform contact and session management functions.
• Access to configure apps within the MS Teams platform.
• Knowledge of MS Teams APIs and webhooks, to create chats and publish/consume messages.

Solution Architecture

Business agents use the MS Teams App to communicate with customers over digital channels. An external web app allows the agents to manage contacts and to trigger conversation initiation, and is accessible directly within MS Teams.

Webex Connect provides the message orchestration layer between MS Teams and the digital channels, consuming triggers from the Web App to initiate a conversation and handling subsequent message routing. MS Teams APIs and webhooks are utilised to create chats and to publish and receive messages. Chats are created as group chats with the app and agent as participants; additional agents may join or leave a chat by via existing MS Teams functionality.

Messages sent by the customer are posted into an MS Teams space by the app, using a card to provide context. The space is named to provide easy identification of the customer.

Customers use their favourite messaging client to communicate with a business from their mobile device.

Components

This solution is comprised of the following components:

Contact synchronization and data archival features are not covered within this guide

Session Manangement

It is important to note that a customer may participate within multiple conversations in MS Teams but, on the guests side, there is usually no concept of multiple conversations. Therefore, session management is required to route messages from the guest to the correct conversation within MS Teams, and vice versa. Within this implementation, the session is maintained to route messages between a customer and their most recent conversation with MS Teams.

Consider the following scenario, where a customer reaches out to a business that has a single WhatsApp number:

The customer messages the business requesting some technical support. The customer is routed through to Agent A, who helps to resolve the customers query. When the customer was routed to Agent A, a session record was created to map the customer to the conversation with Agent A.

Some time later, another agent, Agent B, wishes to discuss another topic with the customer and initiates a new conversation within MS Teams. At this point the session is updated to the conversation with Agent B; messages sent by the customer will now be routed to the conversation with Agent B instead of the conversation with Agent A.

It is not possible for multiple agents to hold simultaneous conversations with the customer due to how session data is maintained and it would be impossible to know where to route the customers reply. Besides, attempting to do so would be confusing for the customer as all messages would appear in a single conversation on their device.

The above could be mitigated where multiple business numbers are being used, with each number used for separate distinct conversations.

Another approach is for multiple agents to participate within the same MS Teams conversation. However, it must be remembered that each agent would see all messages and the approach should only be used where all agents discuss only a single topic at a time (to avoid confusion on the customer side).

Contact Manager App

This app is responsible for providing a web-based UI, including associated backend services, to manage contacts, initiate conversations and to store conversation session data. The app can be embedded within the MS Teams App, to provide a seamless experience for agents.

While development of this application is outside of the scope of this document, basic requirements and guidance is outlined within the following section.

Minimum feature set

Example data schema

The following GraphQL data schema, demonstrates a simple structure for storing contact and session data.

type Contact {
  id: ID!
  name: String
  msisdn: String
}

type Session {
  id: ID!
  customerChannel: String!
  customerChannelId: String!
  collabAgentId: String
  collabGuestId: String
  collabExtra1: String
  collabExtra2: String
  collabExtra3: String
  collabSystemId: String!
  Contact: Contact @hasOne
}

Note that the schema is shared with other collaboration tool integrations, such as the Webex App

Contact attributes

Session attributes

Conversation initiation payload

The following snippet represents the request payload which may be triggered to initiate a conversation

{
    "systemId": "msteams",
    "channel": "whatsapp",
    "channelId": "447xxxxxxxxx",
    "action": "startConversation",
    "agentId": "myWebexUserEmail@myDomain.com",
    "contactName": "Mr Doe"
}

MS Teams Platform Configuration

This solution utilises MS Teams app features, which are configured via the MS Teams Admin Center and MS Teams Developer Portal.

The following resources provide information on the MS Teams components used within this guide.

Microsoft Teams Developer Portal Microsoft Graph APIs RSC Guidance

The following steps require access to an O365 environment. A developer sandbox can be obtained, free of charge, by signing up at:

Microsoft Developer Program

Refer to the following guides to create an App and Bot within the MS Teams developer portal.

Create an app Create a bot

Set the bot Webhook Url to an Inbound Webhook configured within Webex Connect, for payload details refer to the MS Teams Events subsection within the Webex Connect Configuration section of this guide.

When creating your App/Bot ensure to note down your clientId and secret, these will be used for access by the Webex Connect Platform via MS Graph API’s.

The app must be installed either individually into each users Teams App or published to the organisation within the Microsoft Teams Admin Portal

Next, set the required permissions in the MS Teams App, you will need to manually amend the app manifest for some of these.

Sample manifest

Normally, events/messages are only sent to the bot webhook when the bot is explicitly addressed with @Mention. In order to receive all events/messages without @Mention, configure the permissions listed within the following image within the Microsoft Entra Admin Center

You should now have an MS Teams instance, with an App and Bot, where the Bot will be able to send messages to a Webex Connect Inbound Webhook.

Webex Connect Configuration

This section covers the configuration of webhooks and workflows within Webex Connect.

As per the guide prerequisites, it is assumed that the Webex Connect tenant already contains a configured digital channel. While this guide uses WhatsApp and SMS, the principles apply to other digital channels.

Webhooks

This integration requires the configuration of two web hooks, one to consume events from the Contact Manager web app and one to consume events from the MS Teams platform.

Contact Manager Actions

This web hook consumes events generated by the Contact Manager App. While the payload must match that for the app, an example of such a payload is provided below:

{
    "systemId": "webex",
    "channel": "whatsapp",
    "channelId": "447xxxxxxxxx",
    "action": "startConversation",
    "agentId": "myWebexUserEmail@myDomain.com",
    "contactName": "Mr Doe"
}

MS Teams Events

This web hook consumes conversation events from the MS Teams platform.

{
    "text": "Yay",
    "textFormat": "plain",
    "type": "message",
    "timestamp": "2024-03-05T19:13:05.8835423Z",
    "id": "1709665985862",
    "channelId": "msteams",
    "serviceUrl": "https://smba.trafficmanager.net/amer/",
    "from": {
        "id": "29:1IQbfJwhQUZmT6ZmISrERjG0bdyrxqIsygbxdgexHlK3jxA3rN1jMrSKTTiW9ZiPWeITFU7T28eKL_W6rikzlow",
        "name": "Webex CPaaS",
        "aadObjectId": "a358e7e6-145c-4dc6-8f5c-d3f3804f2ffd"
    },
    "conversation": {
        "isGroup": true,
        "conversationType": "groupChat",
        "tenantId": "b7543e8a-92e9-43b6-a09e-5d26c876f3d8",
        "id": "19:2bdf0bc693fb43d8b85c800fe017ce8f@thread.v2"
    },
    "recipient": {
        "id": "28:0549ad3a-7d39-42ca-a83e-d2656fab6400",
        "name": "Webex Connect Chat Bot"
    },
    "entities": [],
    "channelData": {
        "tenant": {
            "id": "b7543e8a-92e9-43b6-a09e-5d26c876f3d8"
        }
    },
    "membersAdded": [{
        "id": "28:0549ad3a-7d39-42ca-a83e-d2656fab6400"
    }]
}

MS Teams Custom Node

This integration uses a custom node to call MS Teams APIs, the following Postman collection may be used to help recreate the custom node within a Connect tenant.

MS Teams Postman Collection

Workflows

The workflows contain the bulk of the integration logic, consuming events from the Contact Manager App, MS Teams Platform and digital channels, to orchestrate conversation journeys and manage contact and session data.

Provision Chat

This workflow manages session data and provisions a new chat within the MS Teams Platform. If a chat already exists, handles closing of the current session, before provisioning the new chat.

The Session nodes perform calls to the Contact Manager Web App APIs

Workflow link: https://presales-uk.eu.webexconnect.io/flowdesigner/view/public/984f0fda-6c26-4f0f-9a9f-d0bdfdf4f8e0

Password: xnb0RDB1xbc@

Web App Action Handler

This workflow consumes events from the Contact Manager Web App to allow agents to initiate conversations with customers.

Workflow link: https://presales-uk.eu.webexconnect.io/flowdesigner/view/public/cdfcacf9-594a-4b4e-99e1-3e126c20574b

Password: xnb0RDB1xbc@

MS Teams Event Handler

The primary function of this workflow is to consume messages from MS Teams and forwards those messages onto the customer via a digital channel. Additionally, handles when agents are added or removed from the chat, and when the app is added to the chat.

The first section of the workflow consumes the message event and branches based on the message type.

The next section of the workflow handles messages posted by the agent and routes to the customers digital channel.

WhatsApp only allows non-template messages to be sent to customers who have messaged the business within the past 24 hours.

WhatsApp Message Template Guidelines

The next section of the workflow provides handling for when agents are added or removed from the chat.

The final section of the workflow updates session data when the MS Teams App is installed within the chat. This captures data, such as service url, that is required for message routing.

Workflow link: https://presales-uk.eu.webexconnect.io/flowdesigner/view/public/34390c7f-fd36-4aa4-be36-382a85113c5d

Password: xnb0RDB1xbc@

WhatsApp Message Handler

This workflow consumes WhatsApp messages sent from the customer and forwards the message to the MS Teams chat, agent statuses such as busy or out of office are detected and managed appropriately. Additionally, this workflow handles the mapping of the customer to an agent.

The first section of the workflow consumes the incoming WhatsApp message and determines if it should be routed to an existing conversation or whether agent mapping is required. Where a message needs to be routed, session and contact data is loaded.

The next section of the workflow executes when an agent routing request is received, or when no existing session is found. A customer contact record is created for the agent, the chat is provisioned and session data is loaded.

It is highly recommended that a production implementation uses mechanisms to detect when provisioning is complete, rather than using an arbitrary delay.|

The next section of the workflow provides handling for the agents presence status. Where the status indicates that the agent may be busy, a message is sent to the customer to inform them there may be a delay in responding. Where the agent is marked as out of office, the customer is sent the out of office message.

The final section of the workflow posts messages into the MS Teams chat and provides a message loop that listens for further messages sent by the customer.

Workflow link: https://presales-uk.eu.webexconnect.io/flowdesigner/view/public/6c04ad7d-c6eb-44e8-a7a3-381a2aa76ae7

Password: xnb0RDB1xbc@

SMS Message Handler

This workflow consumes SMS messages sent from the customer and forwards the message to the Webex agent. Additionally, this workflow handles the mapping of the customer to an agent.

The first section of the workflow consumes the incoming SMS message and determines if it should be routed to an existing conversation or whether agent mapping is required. Where a message needs to be routed, session and contact data is loaded.

The next section of the workflow executes when an agent routing request is received, or when no existing session is found. A customer contact record is created for the agent, the chat is provisioned and session data is loaded.

It is highly recommended that a production implementation uses mechanisms to detect when provisioning is complete, rather than an arbitrary delay.

The final section of the workflow posts messages into the MS Teams chat and provides a message loop that listens for further messages sent by the customer.

Workflow link: https://presales-uk.eu.webexconnect.io/flowdesigner/view/public/29d997fb-4801-46df-8b05-80bc0c8392dd

Password: xnb0RDB1xbc@

Useful Resources

• Webex Connect Developer Documentation
• MS Teams Apps
• MS Graph API - Create Chat
• MS Graph API - Add app to chat
• MS Bot Framework - Get Conversation Member
• MS Bot Framework - Send to conversation
• MS Graph API - Get User
• MS Graph API - Change notifications
• Microsoft documentation for RSC subscriptions