Rich Messaging in Digital Scripts

Digital Any channel, contact, or skill associated with Digital Experience. scripts support rich messaging. Rich messaging is text-based messaging that includes media such as images, buttons, list pickers, quick replies, and rich links. Many digital channels allow the use of rich messaging, but the supported rich media options vary by channel.

Rich content can be sent directly to the contact or it can be displayed in the agent application for agents to interact with. For example, you can create quick reply messages that the agent can choose to send to the contact. It can be used in scripts that handle interactions routed to live human agents or to virtual agents and bots.

Rich Media Content Options

Rich media content is sent as JSON. The JSON must be structured so that the receiving application or system can interpret it and correctly display the content. The appropriate structure varies by application and system. There are several different sets of schemas used in CXone, as shown in the following table.

Schema	Details
TORM (Truly Omnichannel Rich Messaging)	TORM creates rich media elements that work on multiple channels A way for contacts to interact with agents or bots. A channel can be voice, email, chat, social media, and so on.. It supports the following elements: List pickers Quick replies Time pickers Rich links Forms Adaptive cards Most TORM rich media elements can be used as JSON schemas or to create message templates. TORM templates can be sent to the agent application or to the contact. TORM schemas can also be sent directly as JSON using the digital Outbound API. To learn more:  Overview of TORM TORM message templates How to send a TORM template in a script TORM schemas
Non-TORM Templates	Some digital Any channel, contact, or skill associated with Digital Experience. channels support rich media options that use a legacy JSON structure instead of TORM. These options must be created as templates in CXone and are only available for interactions with human agents on the following channels: Digital Email Apple Messages for Business WhatsApp These templates and their schemas are not available for use in scripts.
Adaptive Cards	Developed by Microsoft, Adaptive Cards are a method of creating rich messaging Elements in digital messaging such as buttons, images, menus, and option pickers. content. They're an open card exchange format that allows you to send UI content in a common and consistent way.  With Adaptive Cards, you can send interactive messages that are more complex and helpful than those containing only standard rich media elements. Currently, only digital chat supports Adaptive Cards and Microsoft Teams channels support Adaptive Cards. If messages with Adaptive Cards are sent on other channels, the designated fallback A plain text alternative sent when the destination doesn't support rich media. text is used instead. Currently, adaptive cards can be used:  In messages sent to contacts on digital chat channels. In CXone Bot Builder bot response messages. In SmartAssist virtual agent response messages. To customize digital chat windows. To learn more:  Overview of the use of adaptive cards in CXone. Adaptive card TORM schema. Add adaptive cards to a digital chat channel. Send postback data from adaptive cards in digital chat messages.
Plugin Schemas (Legacy)	These schemas are no longer supported. If you currently use them in your scripts, it's recommended that you switch to one of the supported options described on this page. These schemas can be recognized by the key/value pair "type": "PLUGIN".

TORM

Rich messaging presents a challenge in an omnichannel environment where channels connect to third-party platforms. Most platforms have their own schemas for rich media. This means that to set up a rich media element that would work across several channels, you must look up and code the JSON for that element for each channel. If a platform later changes their schema, it breaks your code.

TORM (Truly Omnichannel Rich Media) attempts to ease this burden. It's an in-house approach developed by NICE CXone to simplify working with rich messaging. TORM provides a single set of JSON schemas for several common rich media elements. When CXone processes the message, the TORM schemas are mapped to the schemas used by the appropriate platform. This removes the need for you to maintain multiple different schemas.

The following table shows the rich media elements that TORM supports. It also shows whether that element is available for use as a message template, JSON schema, or both.  

Element	Template	JSON Schema
List pickers
Quick replies
Time pickers
Rich links
Forms
Adaptive cards

Supported: Not Supported:

TORM Templates

Message templates can be created in the ACD application for the following rich media elements: 

• List pickers
• Quick replies
• Rich links
• Forms

These templates can be assigned to the following digital channels: 

• Apple Messages for Business

• Facebook Messenger

• WhatsApp

• Digital Chat

After being assigned to a channel, the templates can be used in three ways: 

• For agents, set up by an administrator in ACD: A CXone administrator can create a custom component to make templates available in the agent application. When agents send messages to contacts, they can choose from the templates that are available in the agent application they're using.

• For contacts, sent via script: You can include TORM templates in messages sent directly to contacts on supported channels. For example, you could use a list picker as the chat equivalent of an IVR Automated phone menu that allows callers to interact through voice commands, key inputs, or both, to obtain information, route an inbound voice call, or both. to prompt the contact to choose a department they want to chat with. You could also use a form to collect information from the contact, such as their name and a short description of the reason for their inquiry.

Adaptive Cards

Developed by Microsoft, Adaptive Cards are a method of creating rich messaging Elements in digital messaging such as buttons, images, menus, and option pickers. content. They're an open card exchange format that allows you to send UI content in a common and consistent way.  With Adaptive Cards, you can send interactive messages that are more complex and helpful than those containing only standard rich media elements.

The benefit of Adaptive Cards is that you can design your own content, so you're not limited to basic rich media options. Adaptive Cards are built using grid building blocks with many options for interactive elements and multimedia.

Currently, only digital chat and Microsoft Teams channels support Adaptive Cards. If messages with Adaptive Cards are sent on other channels, the designated fallback A plain text alternative sent when the destination doesn't support rich media. text is used instead.

To work with adaptive cards in CXone, you can: 

• Build the JSON in a Snippet action and send it via your script.
• Add adaptive cards directly to a digital chat channel.
• Use adaptive cards in CXone Bot Builder response messages to the contact sent on supported channels.
• Use adaptive cards with your SmartAssist virtual agent on supported channels.

Adaptive cards can be built using the Microsoft adaptive card designer. This tool is availble on for anyone to use.

Fallback Text

Fallback text allows you to specify alternate text to send to contacts for channels A way for contacts to interact with agents or bots. A channel can be voice, email, chat, social media, and so on. that don't support a particular type of rich media content. This is helpful if your organization uses more than one digital Any channel, contact, or skill associated with Digital Experience. channel. It also provides backup in case there are problems rendering the rich media content.

You should include fallback text for all rich media content that you send: 

• For TORM rich media content build in JSON, you can include the fallbackText element in the JSON.
• For rich messaging templates, you should ensure that each template has text specified in the Fallback Text field.
• For messages sent via CXone Bot Builder, use the rich messaging fallback options in the CXone Bot Builder application.
• For messages sent via Virtual Agent Hub, refer to your third-party virtual agent provider's documentation for information about how it handles fallback.

When creating fallback text, the content should communicate a message that's similar to the rich media content. For example, if the rich media content has two buttons that the contact can click to choose between chocolate and vanilla, the fallback text could ask the contact "Do you want chocolate or vanilla?"

Rich Media with Virtual Agents and Bots

You can have virtual agents and bots send rich media in chat-based messages to contacts. A virtual agent or bot sends responses to contacts via a digital channel. You're limited to using rich media elements that the channel supports. If your virtual agent sends messages on multiple channels, make sure you have fallback text defined for each rich media element.

Each response message a virtual agent or bot sends must be configured individually in the virtual agent or bot's configurations. If you want a response to include rich media, you must include that in the response configuration in the virtual agent or bot provider's platform.  

Bot Builder

For bots created using CXone Bot Builder, you can use rich media content in the responses the bot sends to contacts. Bot Builder has several built-in rich media options. These options don't require building JSON. They're available as options in the bot designer UI for use when you create a bot response message

CXone Bot Builder has options for buttons, list pickers, and rich links. Additionally, you can design and send adaptive cards in your bot responses. If you want to use rich media elements that aren't natively offered as an option in Bot Builder but that are supported by the channel you use, you can:

• Set up an integration between your bot and a Studio script. Configure the script with the rich media you want to use in Bot Builder.
• Create a custom bot response action in Bot Builder. This option uses JavaScript. You can code the action to send a stringified JSON object to the contact.

Virtual Agent Hub

For virtual agents set up in Virtual Agent Hub, response messages are typically configured in the management console of the virtual agent provider. For example, if you're working with a Google Dialogflow CX virtual agent, you configure the response messages in the Dialogflow console in your organization's Google Cloud Project. When your Dialogflow administrator configures a response in the management console, the JSON for the rich media element must be included.

An alternative is to create a template in a snippet in your Studio script. Use variables for the values that must come from the virtual agent. Configure the virtual agent's response messages to send just the variables with the appropriate values to the script. In the script, the JSON for the rich media element is constructed in the snippet from the values sent from the virtual agent.

Send TORM Templates with a Script

The GETRICHMESSAGE action used in this script retrieves a dynamic array containing the JSON for all of the rich messaging templates available for the specified point of contact The entry point that an inbound contact uses to initiate an interaction, such as a phone number or email address.. The index number in resultSet.data[x] identifies the array element you want to store in the jsonY.data[x] variable. To discover the list of templates, you can run a trace on your script and look at the contents of the resultSet variable in the trace output.

You can download an example script to use when sending TORM templates via script.

1. Create a template on the Points of Contact Digital page in the ACD application and assign it to the point of contact you want to use it with. You may need assistance from a CXone administrator to complete this step.

2. Create a script with the digital media type.

3. Add a GETRICHMESSAGE action and either an ASKCALLER action or a TeXTMSG action. If the point of contact has more than one template, you also need a SNIPPET action.
4. Configure the ChannelId property in GETRICHMESSAGE with the point of contact you assigned the template to.
5. Add the appropriate code to the SNIPPET action:

   • If you only have one template or if you only want to send one template with this script, use code such as:

     DYNAMIC json1 
     ASSIGN json1.data[1] = resultset.data[1]

   • If you have multiple templates and want to be able to send more than one with this script, use code such as:

     DYNAMIC json1
     DYNAMIC json2
     DYNAMIC json3
     				 
     ASSIGN json1.data[1] = resultset.data[1]
     ASSIGN json2.data[1] = resultset.data[2]
     ASSIGN json3.data[1] = resultset.data[3]

6. Change the index number that identifies the template you want to send. In the example code from the previous step, you would change the index numbers in the resultset.data[x] variable. Do not change the index in the variable you're assigning the template to. In the example code, the variable is jsonY.data[Z], and you could change Y but not Z. Each jsonY variable holds one template.
7. Modify the variable names if you want. If you do, change the variable names as needed in the other actions in the script. For example, resultSet is the default variable name in the resultSet property of GETRICHMESSAGe. The jsonY variables are used in the Message property of AskCaller and Textmsg.
8. Configure AskCaller or Textmsg: 
   1. Set the MessageFormat property to JSON.
   2. Configure Message with the name of the variable that holds the JSON of the template you're sending. It must be sent as a JSON string. You can use variable substitution in this field. If you do, add code to a Snippet to choose the template to send and pass the right variable on.
   3. Configure other properties of the actions as needed, including connecting the branches. Refer to the online help for the ASKCALLER action or TeXTMSG action.

Build JSON in a SNIPPET Action

You can build the JSON for rich media in your script using a Snippet action and send it directly to contacts. To use this option:

• The digital channel must support the type of rich media, if you're sending the content to the contact.
• You must use the schema that the channel expects. This allows the channel to properly display the content. The developer documentation for the channel you're working with may provide this information. The exception to this is if you're using TORM schemas with channels that support them. The channels don't recognize TORM schemas, but CXone converts the schemas to the ones each channel expects before sending them.
• The agent application must support the type of rich media, if you're displaying the content for the agent.

1. Using the tool of your choice, build your JSON structure following the appropriate schema.
2. Test the JSON. This helps ensure that the JSON structure is correct. It can eliminate or reduce the amount of troubleshooting required later due to invalid JSON. For example, you can use the JSON mirror tool.
3. When you have a structure that works, convert it into a string on a single line.
4. In Studio, add a Snippet action to your script.
5. In the Snippet, assign the JSON string to a dynamic object.
6. Add an Askcaller or Textmsg action to the script and configure the Message property with the name of the object that holds the JSON string.
7. Configure the script to send the object containing the JSON to the contact or the agent application.

Send Rich Media to a Contact Directly

1. Verify that the channel you're using supports the rich media you want to use.
2. Set up your script with the rich media you want to send. For example, a TORM template or JSON built in a SNIPPET action.
3. Add an Askcaller or Textmsg action and configure them appropriately.
4. Complete your script.

Send JSON Schemas via API

The following is an example of sending a rich message via the digital Outbound API. You can send messages to the agent application or to contacts. However, rich messages sent this way currently do not display in the agent application. The value of fallbackText is used instead.

curl --location --request POST 'https://api-de-na1.dev.niceincontact.com/dfo/3.0/channels/chat_2360f828-e7dd-4e18-925e-48fba98e8349/outbound' \
--header 'Authorization: Bearer <accessToken>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "thread": {
  "idOnExternalPlatform": "4455006164606838"
},
"messageContent": {
    "type": "TIME_PICKER",
    "fallbackText": "Text sent if rich message is not available on external platform",
    "payload": {
   	   "title": {
	       "content": "Check our new gadget!"
        },
        "timeSlots": [
	       {
            "id": "unique-id-1",
	        "duration": 3600,
	        "startTime": "2017-05-26T08:27:55+00:00"
	        }
	     ],
		"location": {
			"title": {
			    "content": "Check our new gadget!"
			},
			"latitude": 44.44,
			"longitude": 55.55,
			"radius": 33.3
		  }
		}
 },
"recipients": [
    {
	  "idOnExternalPlatform": "57a58d5d-6423-4bd1-9282-533b8b095598",
	  "name": "Frankenstein Monster"
	}
  ]
}'

Limitations of Rich Messaging

Rich messaging in CXone has limitations. Not all digital Any channel, contact, or skill associated with Digital Experience. channels support every rich media element. The agent applications supported in CXone also don't all support every rich media element.

For outbound messages sent to contacts, you can use any rich media element supported by the digital channel used to sent the message. If the channel A way for contacts to interact with agents or bots. A channel can be voice, email, chat, social media, and so on. you use supports a rich media option that's not documented in the CXone Help Center, you can use it. Use the channel provider's schema documentation and build it in a SNIPPET action in your script. For example, if your organization uses Bring Your Own Channel (BYOC), the channel you use might support rich media options that aren't documented on this page.

For rich media content displayed to the agent in the agent application, the content must be supported by the application. If content is not supported by the agent application, the fallback text is displayed for the agent. However, the agent can still send that content to the contact. As long as the channel supports the rich media element, the contact sees the rich content as intended.

Rich Media Support by Channel

Each digital Any channel, contact, or skill associated with Digital Experience. channel supports a specific set of rich media. When working with digital scripts that send rich media content to the contact, verify that the channel the script works with supports the rich media you want to use.  

The following table shows support for rich media type by channel A way for contacts to interact with agents or bots. A channel can be voice, email, chat, social media, and so on.. Channels that are not listed do not currently have rich content support. Any rich content sent through other channels is delivered as the fallback text defined for that channel.

	Adaptive Cards	HTML & Markdown Text	Rich Link	Quick Replies	List Picker	Time Picker	Form message
Apple Messages for Business
Digital Chat
Email				Uses fallback text
Facebook Messenger
WhatsApp
Google Business Messages

Supported:

Not Supported:

Rich Media Support in Agent Applications

Currently, rich media is supported in MAX. Agents can access message templates that may contain rich media content in the following locations in MAX: 

• Non-TORM Templates: Under Message Templates > Choose template.
• TORM Templates: Under Rich Messages > Rich message.

The following table shows support for rich media content by channel that the agent can see in the Customer Card section in MAX.

	Adaptive Cards	HTML & Markdown Text	Rich Link	Quick Replies	List Picker	Time Picker	Form message
Apple Messages for Business
Digital Chat
Email
Facebook Messenger
WhatsApp
Google Business Messages

Supported:

Not Supported: