Webex App as a Channel

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

We will see how to:

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

Prerequisites

This guide assumes that you have:

  • A working knowledge of the Webex platform, including Webex Connect.
  • 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 Webex Platform.
  • Knowledge of Webex APIs to create messages, webhooks and interact with a Guest Issuer application.

Solution Architecture

Solution diagram

Business agents use the Webex App to communicate with customers over digital channels. An external web app allows the agents to manage contacts and to trigger conversation initiation. The web app is hosted within the Webex App as an Embedded Side Bar app.

Webex Connect provides the message orchestration layer between Webex and digital channel, consuming triggers from the Web App to initiate a conversation and handling subsequent message routing. The Webex Guest Issuer integration path is leveraged to surface external customers as guests within the Webex App, allowing communication between agent and customer within a 1:1 space.

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

Components

This solution is comprised of the following components:

Component Notes
Webex App Used by the business agent as a messaging client. Hosts the Embedded app which is used to manage contacts and initiate conversations.
Webex Platform Services APIs, webhooks and associated configuration that facilitates integration with the Webex Connect platform and the Embedded app.
Webex Connect Holds channel assets, custom integration nodes and other configuration, plus associated workflows which facilitate the integration between collaboration tool and other channels.
External Services An external app, including associated services, for managing contacts and triggering conversation initiation. Optionally includes synchronisation with externally managed contacts, for example, Outlook, and data archival to a system of record.
Messaging Client Messaging client for a supported channel, such as SMS / WhatsApp, which a customer uses to communicate with the business agent.

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

Session Manangement

It is important to note that Webex allows guests to participate in multiple conversations but, on the guests side, there may be no concept of multiple conversations. Therefore, session management is required to route messages from the guest to the correct conversation within Webex, and vice versa. Within this guide, we assume that a session is always updated to route messages to the most recent business agent who engaged with the guest.

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

A 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 Agent A.

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

It is not possible for multiple agents to hold simultaneous conversations with the customer due to how session data is maintained. 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 to use Rooms / Spaces within Webex, in this instance, multiple agents could be within the same conversation with the customer; with the session management based on room id rather than agent id. 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 Webex App, as an Embedded Side Bar app, to provide a seamless experience for agents.

Contact manager app

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

Feature Notes
Agent authentication To authenticate the agent within the app. Ideally this would be tied to existing SSO.
Contact management UI and associated backend services to Create, Read, Update and Delete (CRUD) contact records. Data stored must include, at a minimum, the contact name and a channel specific id for each supported digital channel. For example, the channel specific id for WhatsApp and SMS is the customers phone number. APIs to read contact data must be accessible for invocation from Webex Connect.
Conversation initiation UI elements, such as buttons, to trigger conversation initiation for each supported digital channel. Trigger must invoke a Connect webhook to start a conversation initiation journey.
Session management Create, Read, Update and Delete (CRUD) conversation session records for the purposes of message routing between agent and customer channels. APIs must be accessible for invocation from Webex Connect.

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
  Contact: Contact @hasOne
}

Contact attributes

Attribute Notes
id A unique identifier for the contact record
name Name of the customer
msisdn Customer phone number

Session attributes

Attribute Notes
id Unique identifier for the session record
customerChannel Indicates the customer digital channel to which the session relates, for example, ‘whatsapp’ or ‘sms’
customerChannelId The channel specific identifier, for example the customer phone number for WhatsApp or SMS.
collabAgentId Identifies the agent within the Webex platform.
collabGuestId Identifies the guest within the Webex platform.
collabExtra1…3 To store additional session data, as required.

Conversation initiation payload

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

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

Webex Platform Configuration

This solution utilises the Webex Guest Issuer and Embedded App features, which are configured via the Webex Developer portal.

Webex Platform Documentation

Guest Issuer

Guest Issuer allows external users to be granted temporary access to a Webex organization. Guests appear within the Webex application allowing agents to communicate with the guest.

Follow this guide to create a new Guest Issuer application.

Make a note of the Guest Issuer Id and secret, these credentials will be needed later in this guide.

Embedded Apps

Embedded Apps allows external applications to be hosted within the Webex App, which leads to a more seamless experience for agents.

For a full overview of Embedded apps, see this page.

Note: While Embedded Apps can integrate the Webex SDK for a deeper integration, this is not needed for this guide, the app simply needs to be accessible by agents.

Create a new Embedded App within the Webex Developer Portal, ensure the Sidebar type is selected and specify name, description, icon, domain on which the app is hosted and the start page URL.

When the embedded app has been created, it will be accessible within the Webex App for the app creator. The Webex App may need to be restarted before the app will appear.

The embedded app must be approved by the organisation admin before it is accessible organisation wide.

The embedded app can be accessed via the More button. For easier access, the app can be pinned to the side bar via drag and drop.

Sidebar

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/MMS, the principles apply to other digital channels.

Webhooks

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

Contact Manager Actions

This webhook 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"
}

Webex Messages

This webhook consumes messages from the Webex platform.

{
    "id": "Y2lzY29zcGFyazovL3VzL1dFQkhPT0svZW...ItMTI2NjIyNjlkMmE3",
    "name": "Guest Messages Webhook",
    "targetUrl": "https://hooks.us.webexconnect.io/events/EVENTID",
    "resource": "messages",
    "event": "created",
    "orgId": "Y2lzY29zcGFyazovL3VzL09SR0FO...YjNjMS1kNmM1OTRkNmNiMTU",
    "createdBy": "Y2lzY29zcGFyazovL3VzL1BFT...E3Ny1hMjM4OTRlMjRlMTQ",
    "appId": "Y2lzY29zcGFyazovL3VzL0FQUExJQ0F...4Mjc4NGExZjI5NzVj",
    "ownedBy": "creator",
    "status": "active",
    "created": "2023-10-05T14:52:47.021Z",
    "actorId": "Y2lzY29zcGFyazovL3VzL1BF...1hMjM4OTRlMjRlMTQ",
    "data": {
        "id": "Y2lzY29zcGFyazovL3VzL0...tYmQ3OGM4MTU3ZWU0",
        "roomId": "Y2lzY29zcGFyazovL3VzL...RjNDlkZjk3ZTJi",
        "roomType": "direct",
        "personId": "Y2lzY29zcGFyazovL3VzL...YmE3Ny1hMjM4OTRlMjRlMTQ",
        "personEmail": "b6f9c0d5-...-63ae099054b0@domain.com",
        "created": "2023-10-05T14:54:09.085Z"
    }
}

Workflows

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

Webex Guest Auth

This workflow is responsible for authenticating guests with the Webex Platform and is designed to be called from workflows which need a guest access token.

Webex Guest Auth Workflow

Node Description
Configure Webhook A dummy webhook is used for the start node as this flow is only invoked from Call Workflow
Check Token Checks for the presence of an existing Webex access token within a custom variable and verifies whether the token has expired. If the token is still valid, the flow exits
Generate JWT Generates a Json Web Token (JWT) for the guest, using customer data within custom variables
Guest Login Exchanges the JWT for a Webex access token.
Post Processing Stores the access token and expiry within a custom variable for later reuse. This is an optimisation to reduce the need to regenerate tokens before they expire.

When generating the JWT, the source channel and source channel id are combined to create a unique channel based identifier for the guest, this is required as some channels use the same identifier. For example, both SMS and WhatsApp use the customers phone number as the identifier.

Generate JWT

With this approach, a customer who reaches out on both SMS and WhatsApp would have per channel identifiers, such as:

sms_447xxxxxxxxx whatsapp_447xxxxxxxxx

The Generate JWT method is not an API provided by the Webex Platform, an external service, such as an AWS Lambda, is required to perform this function.

Workflow link: https://presales-uk.eu.webexconnect.io/flowdesigner/view/public/a9c03010-eaa5-435a-b75d-815f25d5a441

Password: xnb0RDB1xbc@

Guest Provisioning

This workflow creates and updates session data and provisions a webhook within the Webex Platform to receive messages sent to the guest.

Guest Provisioning Workflow

Node Description
Configure Webhook A dummy webhook is used for the start node as this flow is only invoked from Call Workflow
Start Placeholder used to easily identify the start point when invoking the flow via Call Workflow
Guest Auth Calls the Guest Auth workflow to obtain an access token for the guest user. The access token is needed to call other Webex Platform APIs
Get Guest Details Fetches data for the guest user within the Webex Platform using the access token. The id of the guest returned from this call is required for session management, facilitating the routing of messages from Webex to the external digital channel
Lookup Session Looks for existing session data based on source channel and channel id
Branch Checks whether a session was returned from the lookup
Update Session Updates the existing session with current data, such as agent id and access token
Lookup Contact Looks for contact information based on the customers channel id (phone number). Used to obtain the contact id to populate session data
Create Session Creates a new session record, primarily storing the agent to customer mapping for routing purposes
Create Guest Webhook Calls the Webex Webhooks API to create a webhook entry within the Webex Platform. The target URL should be set to the Webex Messages webhook defined within the ‘Webhooks’ section of this guide. All new messages, created in a Webex space in which the guest is present, will be sent to this webhook.

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

Workflow link: https://presales-uk.eu.webexconnect.io/flowdesigner/view/public/b7486277-94a9-4443-9265-772e75160515

Password: xnb0RDB1xbc@

Create Agent Contact

This workflow creates a contact record for an agent within the Contact Manager Web App.

Create Agent Contact

Node Description
Configure Webhook A dummy webhook is used for the start node as this flow is only invoked from Call Workflow
Start Placeholder used to easily identify the start point when invoking the flow via Call Workflow
Get Agent Details Queries the Contact Manager Web App to obtain the agents details. This is required to associate the contact with the correct agent
Parse Data Parses the data returned from the Get Agent Details node
Create Contact Calls the Contact Manager Web App APIs to create a contact record for an agent
End End of the workflow, used to set a custom variable indicating success of the Create Contact call

Workflow link: https://presales-uk.eu.webexconnect.io/flowdesigner/view/public/bc429680-77c6-48df-8712-005f15770279

Password: xnb0RDB1xbc@

Web App Action Handler

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

Web App Action Handler

Node Description
Configure Webhook Triggered in response to events sent from the Contact Manager Web App. See ‘Contact Manager Actions’ within the ‘Webhooks’ section for payload details
Branch Branches based on the action received in the event payload. Currently supports the ‘startConversation' action
Provision Guest Calls the Provision Guest workflow to perform the setup required for message exchange between Webex and the external channel
Send Message Sends a message to the agent within Webex. This serves to create the conversation within Webex so that the agent can message the user. Where a conversation already exists, this posts a message into that space to draw the agents attention

Workflow link: https://presales-uk.eu.webexconnect.io/flowdesigner/view/public/e9972988-be15-443e-88cf-ba9e63797cd6

Password: xnb0RDB1xbc@

Webex Message Handler

The primary function of this workflow is to consume messages from the Webex Messages webhook and forward those messages onto the customer via a digital channel.

Webex Message Handler

The first section of the workflow consumes the Webex message event and performs a sender and session check.

Webex Message Handler Part 1

Node Description
Configure Webhook Triggered in response to new message events sent from the Webex Platform. See ‘Webex Messages’ within the ‘Webhooks’ section for payload details
Sender? Checks the actorId contained in the received message data to determine if the message was created by an agent or the guest. This is required as the webhook is triggered by Webex for messages created by both agent and guest
End Placeholder This node only exists to better visualise the flow exit due to the message being created by the guest
Lookup Session Looks up session data based on the guest user id. The guest user id is obtained from the createdBy attribute in the message data
Has Session? Checks whether a valid session was returned in the session lookup. If no session was returned, the flow exits. A session should always exist at this point

The next section of the workflow handles guest authentication and fetches message content.

Webex Message Handler Part 2

Node Description
Guest Auth Calls the Guest Auth workflow to obtain an access token for the guest user. The access token is needed to call other Webex Platform APIs
New Token? Checks whether a new access token has been generated
Update Session Updates the current session record with the new access token
Get Message Details Calls the Webex Messaging API to fetch full message data

For security, Webex does not pass all message data via the webhook. Therefore, it is necessary to call the Webex Messaging API to fetch the complete message.

The next section of the workflow checks the message text, looks for and processes an attachment, and determines the digital channel to which the message should be routed.

Webex Message Handler Part 3

Node Description
Sanitize Message Text Checks whether message text is present and, where missing, sets a default value. This is required for attachment only messages, due to destination channel restrictions
Has Attachment? Determines whether an attachment is present within the message data
Cache Attachment Invokes an external service to fetch the attachment from Webex and transfer it to a location accessible by message send nodes
Determine Channel Branches based on the channel information within the current session, facilitating message delivery to the correct digital channel

The next section of the workflow handles routing of the message to the SMS/MMS channel.

Webex Message Handler Part 4

Node Description
Has Attachment? Determines whether an attachment is present within the message data
SMS Sends an SMS to the customer
Send MMS Uses the Messaging API to send an MMS message to the customer

The final section of the workflow handles routing of messages to the customer via the WhatsApp channel.

Webex Message Handler Part 5

Node Description
Has Attachment? Determines whether an attachment is present within the message data
Determine Image Type Looks at the mime type of the attachment to determine if it’s a PNG or JPEG image
Send JPEG Sends a JPEG image attachment to the customer via WhatsApp
Send PNG Sends a PNG image attachment to the customer via WhatsApp
Send WhatsApp Msg Sends a text message to the customer via WhatsApp
Send WhatsApp Template Used to send a templated message to the customer via WhatsApp. This is sent if standard image or text messages fail due to WhatsApp engagement rules

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

Workflow link: https://presales-uk.eu.webexconnect.io/flowdesigner/view/public/a3e1367b-1e51-453c-ae82-b7819a74616e

Password: xnb0RDB1xbc@

WhatsApp Message Handler

This workflow consumes WhatsApp 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.

WhatsApp Message Handler

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.

WhatsApp Message Handler Part 1

Node Description
Configure WhatsApp Event Consumes the incoming WhatsApp message
Is Routing Request? Inspects message content to determine if it represents a routing request. For demo purposes this looks for the presence of webexAgent_{AGENTID}
Lookup Session Queries the Contact Manager Web App to look for an existing chat session
Has Session Id? Looks at the response of the Lookup Session node to see if a session exists (indicated by the presence of the session id), and branches accordingly

The next section of the workflow provides a message loop to authenticate the customer within Webex, updates session data, forwards the message to the Webex agent and listens for further messages.

WhatsApp Message Handler Part 2

Node Description
Remove keyword The number used in the demo implementation is shared with other demos on the tenant, hence a keyword is used to trigger the initial journey. This node removes the keyword from the message so it is not forwarded to the Webex agent. This wouldn’t be needed for a production implementation
Guest Auth Calls the Guest Auth workflow to obtain an access token for the guest user. The access token is needed to call other Webex Platform APIs
Is New Token? Checks whether a new access token has been generated
Update Session Updates the current session record with the new access token
Detect Attachment Inspects the WhatsApp message to detect, and extract, any attachment data. Branches based on whether an attachment was detected
Send Message with Attachment Sends a message with attachment to the Webex agent
Send Message Sends a text only message to the Webex agent
Receive Listens for further messages from WhatsApp
Session has ended Sends a WhatsApp message informing the customer that the current chat session has ended, including instruction on how to re-engage. May not be needed for a production implementation

The next section of the workflow executes when no existing session has been found, or when an agent routing request is received. Information is gathered to support agent mapping and session initiation is performed.

WhatsApp Message Handler Part 3

Node Description
Get Contact Queries the Contact Manager Web App to determine if the customer is already assigned to an agent
Check Response Checks the response of the Get Contact request to determine if an existing contact record was found
Provision Guest Calls the Provision Guest workflow to perform the setup required for message exchange between Webex and the external channel
Request Name Sends a message to the customer via WhatsApp, requesting the input of their name
Receive Listens for an incoming WhatsApp message to gather customer input
Request Agent Email Sends a message to the customer via WhatsApp requesting the email address of the agent they wish to contact. This is for demo purposes, where a QR code with a routing command hasn’t been used to start the workflow
Parse Agent Id Extracts the agent email from the message that triggered the workflow
Please Wait Sends the customer a WhatsApp message asking them to wait while the input data is processed

The final section of the workflow concludes the agent mapping process by creating an agent contact record and messages the user, before routing through to an agent.

WhatsApp Message Handler Part 4

Node Description
Create Agent Contact Invokes Contact Manager Web App APIs to create a contact record for an agent
Was Contact Created? Checks the response of the Create Agent Contact node to determine if a contact record was created successfully
Conversation Initiated Sends a WhatsApp message to the customer informing them that a conversation with the agent has been initiated
Agent not found Sends a WhatsApp message to the customer informing them that they could not be connected to an agent. This may occur if the specified agent email did not match an agent within the business

Workflow link: https://presales-uk.eu.webexconnect.io/flowdesigner/view/public/9cb9a440-e722-4295-a68e-f90fdcec66fe

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.

SMS Message Handler

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.

SMS Message Handler Part 1

Node Description
Configure SMS Event Consumes the incoming SMS message
Is Routing Request? Inspects message content to determine if it represents a routing request. For demo purposes this looks for the presence of webexAgent_{AGENTID}
Lookup Session Queries the Contact Manager Web App to look for an existing chat session
Has Session Id? Looks at the response of the Lookup Session node to see if a session exists (indicated by the presence of the session id), and branches accordingly

The next section of the workflow provides a message loop to authenticate the customer within Webex, updates session data, forwards the message to the Webex agent and listens for further messages.

SMS Message Handler Part 2

Node Description
Remove keyword The number used in the demo implementation is shared with other demos on the tenant, hence a keyword is used to trigger the initial journey. This node removes the keyword from the message so it is not forwarded to the Webex agent. This wouldn’t be needed for a production implementation
Guest Auth Calls the Guest Auth workflow to obtain an access token for the guest user. The access token is needed to call other Webex Platform APIs
Is New Token? Checks whether a new access token has been generated
Update Session Updates the current session record with the new access token
Send Message Sends a text only message to the Webex agent
Receive Listens for further SMS messages
Session has ended Sends a SMS message informing the customer that the current chat session has ended, including instruction on how to re-engage. May not be needed for a production implementation

The next section of the workflow executes when no existing session has been found, or when an agent routing request is received. Information is gathered to support agent mapping and session initiation is performed.

SMS Message Handler Part 3

Node Description
Get Contact Queries the Contact Manager Web App to determine if the customer is already assigned to an agent
Check Response Checks the response of the Get Contact request to determine if an existing contact record was found
Provision Guest Calls the Provision Guest workflow to perform the setup required for message exchange between Webex and the external channel
Request Name Sends a message to the customer via SMS, requesting the input of their name
Receive Listens for an incoming SMS message to gather customer input
Request Agent Email Sends a message to the customer via SMS requesting the email address of the agent they wish to contact. This is for demo purposes, where a QR code with a routing command hasn’t been used to start the workflow
Parse Agent Id Extracts the agent email from the message that triggered the workflow
Please Wait Sends the customer a SMS message asking them to wait while the input data is processed

The final section of the workflow concludes the agent mapping process by creating an agent contact record and messages the user, before routing through to an agent.

SMS Message Handler Part 4

Node Description
Create Agent Contact Invokes Contact Manager Web App APIs to create a contact record for an agent
Was Contact Created? Checks the response of the Create Agent Contact node to determine if a contact record was created successfully
Conversation Initiated Sends a SMS message to the customer informing them that a conversation with the agent has been initiated
Agent not found Sends a SMS message to the customer informing them that they could not be connected to an agent. This may occur if the specified agent email did not match an agent within the business

Workflow link: https://presales-uk.eu.webexconnect.io/flowdesigner/view/public/d6cd4abd-b2f1-43b7-93e1-b1609c60aedb

Password: xnb0RDB1xbc@

MMS Message Handler

This workflow consumes MMS messages sent from the customer and forwards the message to the Webex agent.

MMS Message Handler

The first section of the workflow consumes and parses MMS data.

MMS Message Handler Part 1

Node Description
Configure MMS Event Consumes the incoming MMS
Parse MMS Data Parses the MMS data to extract attachments
Request Text Content Performs an HTTP request to fetch the content of the text attachment
Sanitize Message Text Checks whether text is present and provides a default value where text is not present

The final section of the workflow provides session and auth token management, and forwards the MMS message to the Webex agent.

MMS Message Handler Part 2

Node Description
Lookup Session Queries the Contact Manager Web App to look for an existing chat session
Has Session Id? Looks at the response of the Lookup Session node to see if a session exists (indicated by the presence of the session id), and branches accordingly
Session not found Messages the customer to inform them no session has been found
Guest Auth Calls the Guest Auth workflow to obtain an access token for the guest user. The access token is needed to call other Webex Platform APIs
Is New Token? Checks whether a new access token has been generated
Update Session Updates the current session record with the new access token
Send Message Sends a message with attachment to the Webex agent

Workflow link: https://presales-uk.eu.webexconnect.io/flowdesigner/view/public/d435960a-1dc6-4026-83c0-39638379e80c

Password: xnb0RDB1xbc@

Useful Resources