BYOC Middleware

Bring Your Own Channel (BYOC) lets you integrate a digital Any channel, contact, or skill associated with Digital Experience. messaging channel that's not supported by CXone. For the unsupported channel to work with CXone, you must build and host your own middleware software. The middleware acts like a bridge or adapter between the unsupported platform and the Digital Experience platform in CXone. It translates between two potentially incompatible APIs and allows them to communicate back and forth. This communication could be, for example, the agent sending a message to the contact The person interacting with an agent, IVR, or bot in your contact center.. BYOC can support text-based interactions that are inbound, outbound, or both.

The API specification below explains the APIs that you must implement in your middleware.

After implementing the middleware, you will be able to provide the following to your CXone administrator:

OAuth credentials
Fully-qualified URLS for callbacks from CXone

Your administrator must use this information for additional setup within CXone, explained in the BYOC overview.

If BYOC doesn't fit your use case for integrating an external chat, you may want to use the web SDK.

High level diagram showing where the middleware that you need to create exists between the channel and CXone.

The Jungle, Inc. just set up a BYOC integration with The Watering Hole™, a new social media platform that extends their reach to the African savanna market. The Watering Hole™ is a messaging board where animals can post content, plus it also has a live chat where animals can have peer to peer conversations. The Jungle uses the chat widget, which is a front-end integration of the BYOC channel, allowing animals on the savanna to message The Jungle directly with the live chat. When an animal sends an initial message, the middleware uses the DE Create message API to create a message on the Digital Experience platform and queue it to the appropriate channel. After an agent accepts the contact and replies, Digital Experience uses the outbound POST messages reply endpoint that's hosted on the BYOC middware to post agents reply to the middleware. Then, the middleware can take that messaging information and display it to the animal along with any other styling. This process continues back and forth until the interaction concludes.

sequenceDiagram autonumber participant P as 3rd Party Platform participant M as Middleware participant CX as DFO (CXone) loop P->>M: Send 3rd Party Message M->>CX: Relay 3rd Party Message CX->>M: Send DFO Message M->>P: Relay DFO Message end

In addition to handling messages back and forth through The Watering Hole™, their developers also solved two scenarios for ending chats: if an animal closes their chat widget and if the agent is required to stop the conversation.

First, if an animal closes their widget, navigates away, or abandons the chat, The Jungle developers set a two-minute timer. If the chat is idle for two minutes, they display a message to the animal, asking if they're still available and begin a 20-second countdown. After the 20 seconds completes, CXone ends the interaction and the agent can conclude with any dispositions or notes.

Second, The Jungle developers handled when the agent ends a conversation. Perhaps the agent is finished talking, or maybe the animal might be overly angry and belligerent. In these instances, the agent must be able to end the interaction and the angry animal must be prevented from continuing to angrily chat on the thread. The developers used the Digital Engangement APIs to get the status of the thread and stop the customer from replying.

The Watering Hole™ also allows agents from The Jungle, Inc. to send direct messages to animals on the savanna. For these cases, they used the channel/outbound method rather than the reply method since it creates a new message thread. From there, the interaction happens just the same as any other animal-initiated interaction where the middleware calls the create message API to post responses. Then, the Digital Experience platform responds through the reply endpoint since they're sending replies to an existing thread.

Technical Integration

The middleware integration is composed of two parts:

Authentication
The set of middleware endpoints that you must implement to interact with CXone

Authentication

When building your middleware, be sure to handle two types of authentication:

From middleware to CXone:
Standard OAuthapplication authentication , which is required to work with CXone APIs.
From CXone to middleware:
Authorization your middleware must perform on API calls made by CXone. When a message comes from the agent client and is sent to the BYOC messaging channel, the middleware checks for an access token to ensure that the message is coming from CXone. Use the /token endpoint in the Authorization API documented below.

Middleware Endpoints

Using the endpoints in the API specification below, you can accomplish certain segments of communication, like creating a method or mechanism for each activity. You have the authentication mechanism, the mechanism for adding new channels, and the mechanism for messages being sent from those channels. You aren't just creating a channel, you're creating the method that creates communication channels with the 3rd party platform. These communication channels that are created can then send messages back and forth.

Service Expectations

Your service should be operated in high-available mode with possible auto-scale in case of higher traffic or traffic spikes.
Your service and its availability should be fully monitored.
Your service needs to be fast to provide good quality for both agent and contacts. Your API responses should be below 500 MS.
Be sure to have a good connection of the network to the AWS data center. You can verify this against the Digital Engagement APIs .

Related APIs

The following are CXone APIs that are frequently used to set up Digital Experience chat functionality.

POST /channels/{channelId}/messages: Creates and stores a message in the Digital Experience platform.
POST /channels/{channelId}/outbound: Sends an outbound message to the connected channel and stores the message in the Digital Experience platform.
PUT /customers/custom-field-definitions: Creates or updates a customer custom field. Customer custom fields allow you to collect data from your contacts. This data might be about the contact or the issue they're having.
POST /channels: Creates a new Digital Experience channel using the channelIntegrationID, which is generated when adding a BYOC integration in the Digital Experience section of CXone. You can use this API to create the BYOC channel.

BYOC Middleware IDs

The following table explains the different IDs that you must use for BYOC channel API calls.

ID	Details
client_id	Along with the client_secret, these are produced by CXone when you generate an access token. This token allows you to make API calls as part of OAuth2.0.
brandId	The Digital Experience equivalent of a tenant High-level organizational grouping used to manage technical support, billing, and global settings for your CXone environment ID.
tenantId	The ID of the CXone tenant. This is the tenant on which the chat channel was created. This is a longer alphanumeric string, such as: 86f85ac-aaed-48e4-9b90-89e31572c627.
businessUnitId	The ID of the business unit on which the chat channel was created. You can find this in CXone under ACD > Business Units in the ACD Configuration section.
channelIntegrationId	The ID of the digital chat channel created in Digital Experience. To set up a BYOC channel, you must create or use an existing digital chat channel.
idOnExternalPlatform	An identifier for any entity on the external platform. For example, this could be the ID of a Facebook post, email recipient, or a WhatsApp user ID. Another example is an SMS channel; this ID would be the contact's phone number. These IDs are generated by the external platform. You could have thread.idOnExternalPlatform, channel.idOnExternalPlatform, message.idOnExternalPlatform, and so on.
ownerUserId	The ID of the user who created the digital chat channel.
threadId	A group of messages or contacts, depending on the type of channel. For example, it could be a series of chat messages between an agent and a contact. The thread is the object that contains messages, and messages are structured by the author of the messages. For channels like Facebook, a post is the thread. Elements or members of the thread object contain contacts, which are people who respond to the post. A threadId identifies an entire conversation, and all messages within a conversation has a message ID.