Set Up BYOC Middleware

Bring Your Own Channel (BYOC) lets you use a digital messaging channel that's not yet 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 channel and the Digital First Omnichannel (DFO) platform in CXone. It translates between two potentially incompatible API specifications and allows them to communicate back and forth. This communication could be, for example, the agent sending a message to the contact. The API specification below explains the APIs that you must implement in your middleware.

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

The following diagram shows messages being sent back and forth between the CXone DFO platform and the BYOC channel.

The following diagram shows messages being sent back and forth between the CXone DFO platform and the BYOC channel.:

Shows the flow of outbound messages from DFO through the middleware to the chat window.

Technical details of the middleware:

  • Your middleware must provide an API method for the channel or app to send messages to the DFO platform.
  • DFO sends HTTPS requests to your middleware service when an agent or a bot sends an outbound message.
  • The middleware service can receive HTTP requests (callbacks) from CXone APIs.
  • When the agent replies to a message, DFO calls the middleware's outbound reply endpoint. When calling this endpoint, it expects an HTTP 200 reply with the message ID from the external platform included in a JSON payload.

BYOC Example

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 DFO Create message API to create a message on the DFOplatform and queue it to the appropriate channel. After an agent accepts the contact and replies, DFO 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.

Ending Chats Example

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.

Sending Replies Example

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 DFO platform responds through the reply endpoint since they're sending replies to an existing thread.

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

Process Overview

The following provides a high-level overview of the process to integrate a BYOC channel with CXone. The CXone online help provides comprehensive instructions.

  • Plan the technical details of your middleware using the information on this page. Start building your middleware.
  • Provide technical details to an administrator, like the OAuth2.0 client_secret and client_id, fully-qualified URLs for HTTPS callbacks from CXone, and so forth.
  • In CXone, an administrator sets up the following:
    • Create a digital agent by enabling an existing employee or creating a new employee.
    • Create a digital skill for the BYOC channel and ensure that the digital agent is assigned the skill.
    • Add a BYOC integration in the DFO section of CXone.
    • Set up the channel in the Points of Contact Digital section of DFO using the integration ID.
    • Add the BYOC channel to a routing queue associated with the digital skill.

The following diagram shows technical details of the overall process.

Shows configuration flow and relationships between the Admin, DFO, and middleware. Shows which part is responsible for each action.

Required Authentication

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

  • Standard OAuth2.0 authentication, which is required to work with CXone APIs.
  • authorization your middleware must perform on API calls made by CXone. For instance, 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 below.

Threads

Digital channels use a concept of a thread. A thread is 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 Facebook post is the thread, and 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.

Authors, Contacts, and Recipients

An author is the party who created a message. This could be the agent, whose identifier would be their access token. It could also be a contact who made a Facebook post or responded to a Facebook post. Recipients are receivers of a message. Recipients are not mandatory to configure; they're typically only used for email channels, but could also be used for other channels. For example, the recipient of a Facebook post is the Facebook page. The isPrimary and isPrivate properties are relevant to email recipients. Private recipients indicate that they're CC'd or BCC'd to the email thread. If you configure recipients, set up address validation in the middleware.

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 DFO equivalent of a business unit 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.
channelId The ID of the digital chat channel created in DFO. To set up a BYOC channel, you must create or use an existing digital chat channel.
idOnExternalPlatform This ID shows up in different objects depending on the type of channel. In general, it identifies a thread on the external platform. For example, this could be the ID of a Facebook post or a Twitter user ID. Another example is an SMS channel; this ID would be the contact's phone number. These IDs are supplied by the external platform. For example, you could have thread.idOnExternalPlatform, channel.idOnExternalPlatform, or message.idOnExternalPlatform.
ownerUserId The ID of the user who created the digital chat channel.

Related APIs

The following are CXone APIs that are frequently used to set up DFO functionality.

POST /channels/{channelId}/messages

Creates and stores a message in the DFO platform.

POST /channels/{channelId}/outbound

Sends an outbound message to the connected channel and stores the message in the DFO 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. You can learn more about custom fields in the online help This link opens the online help in a new browser tab..

POST /channels

Creates a new DFO channel using the channelIntegrationID, which is generated when adding a BYOC integration in the DFO section of CXone. You can use this API to create the BYOC channel.

Middleware API Specification

The following specification explains the APIs that your middleware must provide to the DFO platform in CXone.

Loading...