JSON schema - Messages | Contact Center Apps
Use the DialogFlow custom payload
Add multiple custom payloads in DialogFlow. To use DialogFlow's custom payload, you don't need to use nested message formats. The maximum total body size for any single message is 32 KB, or about 32,000 characters.
| Field | Required | Value | Description |
|---|
type | Yes | String | Refer to the message content part. |
value | Yes | Object | Refer to the message content part. |
Use the DialogFlow fulfillment service webhook payload
Message text
{
"type": "text",
"value": "Hi, I'm your virtual agent!"
}
| Field | Required | Value | Description | Limitation |
|---|
value | Yes | String | plain text | Maximum text length: 2048 characters. |
HTML
{
"type": "html",
"value": "<b>Please type your query below</b> \n\n<h5>To connect with Customer Care Team / Live Agent type \"<b>Contact us</b>\"</h5><h5>To access case management and contact our support team, enter \"<b>Contact Us</b>\"</h5>"
}
| Field | Required | Value | Description | Limitation |
|---|
value | Yes | String | Standard HTML format | Maximum text length: 4096 characters. |
Markdown
{
"type": "markdown",
"value": "## This text is **bold**."
}
| Field | Required | Value | Description | Limitation |
|---|
value | Yes | Object | Standard Markdown format | Maximum text length: 4096 characters . |
Quick replies - Picker
{
"type": "picker",
// "type": "quickReplies",
"value": {
"title": "Please make your choice",
"options": [
{
"label": "Yes",
"value": "yes"
},
{
"label": "No",
"value": "no"
}
]
}
}
NOTE picker and quickReplies are equivalent. They are each other's aliases.
| Field | Required | Value | Description | Limitation |
|---|
title | No | String | | Maximum text length：1024 characters. |
mandatory | No | Boolean | If true, the live chat client disables the input box when the quick reply button is not clicked.Default is false. | Only works with Contact Center livechat SDK. |
options | Yes | List | | Maximum list size: 20. |
options.label | Yes | String | Display Name | Maximum length：128 characters. |
options.value | Yes | String | The identify value | Maximum length：128 characters. |
Quick reply response to DialogFlow (detectIntent)
{
"session": "projects/your-project-id/agent/sessions/unique-session-id",
"queryInput": {
"text": {
"text": "Yes",
"languageCode": "en-US"
}
},
"queryParams": {
"contexts": [
{
"name": "projects/your-project-id/agent/sessions/unique-session-id/contexts/zcc-engagement-context",
"lifespanCount": 100,
"parameters": {
"engagementId": {
"stringValue": "b813576e-5301-4b0c-b448-cc09c32ed72a-0fffcc35",
"kind": "stringValue"
},
"consumerName": {
"stringValue": "Tom",
"kind": "stringValue"
}
}
}
],
"payload": {
"action": "optionSubmit",
"data": {
"interactionId": "a806116e-5301-4b0c-b448-cc09c32ed72a-0fffcb44",
"interacted": true,
"value": "yes",
"originMessage": {
"type": "quickReplies",
"value": {
"title": "Please make your choice",
"options": [
{
"label": "Yes",
"value": "yes"
},
{
"label": "No",
"value": "no"
}
]
}
}
}
}
}
}
| Field | Value | Description |
|---|
session | String | The dialog flow session identification. |
queryInput | JSON (Dialog Flow standard format) | The text value is equal to the option's label value. |
queryParams.contexts | JSON (Dialog Flow standard format) | See more in (Parameters)[#parameters-in response-to-dialogflow]. |
queryParams.payload | JSON (Contact Center schema) | See more in (Parameters)[#parameters-in response-to-dialogflow]. |
Card
{
"type": "card",
"value": {
"title": "your title",
"description": "This text is **bold**.",
"imageUrl": "https://example.com/image.jpg",
"options": [
{
"type": "option",
"label": "Select case 1",
"value": "case1"
},
{
"type": "link",
"label": "More",
"value": "https://example.com/link"
}
]
}
}
| Field | Required | Value | Description | Limitation |
|---|
title | No | String | | Maximum text length：256 characters. |
description | No | String | Standard Markdown format | Maximum text length: 4096 characters. |
imageUrl | No | String | Image URL | Maximum text length：1024 characters. |
mandatory | No | Boolean | If true, and the options list contains at least one option type item - such as a button - the live chat client disables the input box if the button is not clicked.Default is false. | |
options | No | List | Refer to Options | Maximum option number：20. |
Card option (type option)
| Field | Required | Value | Description | Limitation |
|---|
label | Yes | String | Display Name | Maximum length: 128 characters. |
value | Yes | String | The identify value | Maximum length：128 characters. |
Card link (type link)
| Field | Required | Value | Description | Limitation |
|---|
label | Yes | String | Display Name | Maximum length：128 characters. |
value | Yes | String | URL | Maximum length：1024 characters. |
Card option response to DialogFlow (detectIntent)
{
"session": "projects/your-project-id/agent/sessions/unique-session-id",
"queryInput": {
"text": {
"text": "Yes",
"languageCode": "en-US"
}
},
"queryParams": {
"contexts": [
{
"name": "projects/your-project-id/agent/sessions/unique-session-id/contexts/zcc-engagement-context",
"lifespanCount": 100,
"parameters": {
"engagementId": {
"stringValue": "b813576e-5301-4b0c-b448-cc09c32ed72a-0fffcc35",
"kind": "stringValue"
},
"consumerName": {
"stringValue": "Tom",
"kind": "stringValue"
}
}
}
],
"payload": {
"action": "optionSubmit",
"data": {
"interactionId": "a806116e-5301-4b0c-b448-cc09c32ed72a-0fffcb44",
"interacted": true,
"value": "yes",
"originMessage": {
"type": "quickReplies",
"value": {
"title": "Please make your choice",
"options": [
{
"label": "Yes",
"value": "yes"
},
{
"label": "No",
"value": "no"
}
]
}
}
}
}
}
}
Carousel
{
"type": "carousel",
"value": {
"cards": [
{
"title": "title 1",
"description": "* This is the first item.\n * This is the second item.",
"imageUrl": "https://example.com/image.jpg",
"options": [
{
"type": "option",
"label": "Select case 1",
"value": "case1"
},
{
"type": "link",
"label": "More",
"url": "https://example.com/link"
}
]
},
{
"title": "title 2",
"description": "I just love **bold text**.",
"imageUrl": "https://example.com/image2.jpg",
"options": [
{
"type": "option",
"label": "Select case 1",
"value": "case1"
},
{
"type": "link",
"label": "More",
"url": "https://example.com/link"
}
]
}
]
}
}
| Field | Required | Value | Description | Limitation |
|---|
cards | Yes | List | The content referring to Card | Maximum size：10. |
Form
{
"type": "form",
"value": {
"name": "info_collection_form",
"title": "your title",
"subtitle": "I really like using Markdown.",
"fields": [
{
"type": "text",
"label": "Name",
"key": "name",
"required": true,
"defaultValue": ""
},
{
"type": "single-select",
"label": "Education",
"key": "education",
"required": true,
"options": [
{
"label": "High School Diploma",
"value": "high_school"
},
{
"label": "Associate Degree",
"value": "associate"
},
{
"label": "Bachelor's Degree",
"value": "bachelor"
},
{
"label": "Doctoral Degree (Ph.D.)",
"value": "doctor"
},
{
"label": "Other",
"value": "other"
}
],
"defaultValue": ""
}
]
}
}
| Field | Required | Value | Description | Limitation |
|---|
name | No | String | No effect on UI | Maximum text length：128 characters. |
title | No | String | | Maximum text length：256 characters. |
subtitle | No | String | | Maximum text length: 1024K characters. |
mandatory | No | Boolean | If true, and the field list contains at least one field element, the live chat client disables the input box before the form is submitted.Default: false | Works with Contact Center SDK chat only. |
fields | Yes | List | Refer to textInput, select, multi-select | Maximum size：20. |
displayStyle | No | inline or overlay | Default is inline | overlay: inline: |
Text Input
{
"type": "text",
"label": "Name",
"key": "name",
"required": true,
"defaultValue": "",
"pattern": "text"
}
| Field | Required | Value | Description | Limitation |
|---|
label | Yes | String | | Maximum text length：128 characters. |
key | Yes | String | | Maximum length：128 characters. |
required | No | Boolean | Default is false. | |
defaultValue | No | String | | Maximum text length：256 characters. |
pattern | No | String | default text``text，no ruleemail, must be in email address formatinteger, require input of positive integers.decimal, require decimal inputcustom, use the regex set in customRegex field to do the validation. | |
customRegex | No | String | regular expression | Maximum text length：128 characters. |
errorLabel | No | String | The error message to show while the data is invalid. | Maximum text length：128 characters. |
Single Select
{
"type": "single-select",
"label": "Education",
"key": "education",
"required": true,
"options": [
{
"label": "High School Diploma",
"value": "high_school"
},
{
"label": "Associate Degree",
"value": "associate"
},
{
"label": "Bachelor's Degree",
"value": "bachelor"
},
{
"label": "Doctoral Degree (Ph.D.)",
"value": "doctor"
},
{
"label": "Other",
"value": "other"
}
],
"defaultValue": ""
}
| Field | Required | Value | Description | Limitation |
|---|
label | Yes | String | | Maximum text length：128 characters. |
key | Yes | String | | Maximum length：128 characters. |
required | No | Boolean | Default is false. | |
defaultValue | No | String | option.value | |
options | Yes | List | | Maximum size：32. |
Option
{
"label": "Male",
"value": "male"
}
| Field | Required | Value | Description | Limitation |
|---|
label | Yes | String | Display name | Maximum length：128 characters. |
value | Yes | String | The identify value | Maximum length：128 characters. |
Multi-select
{
"type": "multi-select",
"label": "Make you chocie",
"key": "option",
"required": true,
"options": [
{
"label": "Option1",
"value": "1"
},
{
"label": "Option2",
"value": "2"
},
{
"label": "Option3",
"value": "3"
}
],
"defaultValue": ["1", "2"]
}
| Field | Required | Value | Description | Limitation |
|---|
label | Yes | String | | Maximum text length：128 characters. |
key | Yes | String | | Maximum length：128 characters. |
required | No | Boolean | default false | |
defaultValue | No | List | option.value | |
options | Yes | List | | Maximum size：32. |
Option
{
"label": "Male",
"value": "male"
}
| Field | Required | Value | Description | Limitation |
|---|
label | Yes | String | Display Name | Maximum length：128 characters. |
value | Yes | String | The identify value | Maximum length：128 characters. |
Form response to DialogFlow (detectIntent)
{
"session": "projects/your-project-id/agent/sessions/unique-session-id",
"queryInput": {
"text": {
"text": "info_collection_form",
"languageCode": "en-US"
}
},
"queryParams": {
"contexts": [
{
"name": "projects/your-project-id/agent/sessions/unique-session-id/contexts/zcc-engagement-context",
"lifespanCount": 100,
"parameters": {
"engagementId": {
"stringValue": "b813576e-5301-4b0c-b448-cc09c32ed72a-0fffcc35",
"kind": "stringValue"
},
"consumerName": {
"stringValue": "Tom",
"kind": "stringValue"
}
}
}
],
"payload": {
"action": "formSumit",
"data": {
"interactionId": "a806116e-5301-4b0c-b448-cc09c32ed72a-0fffcb44",
"skipped": false,
"values": [
{
"key": "name",
"type": "textInput",
"value": "Tom"
},
{
"key": "education",
"type": "select",
"value": "bachelor"
},
{
"key": "option",
"type": "multi-select",
"value": ["1", "2"]
}
],
"originMessage": {
"type": "form",
"value": {
"title": "your title",
"description": "<p>I really like using Markdown.</p> ",
"fields": [
{
"type": "textInput",
"label": "Name",
"key": "name",
"required": true,
"defaultValue": ""
},
{
"type": "select",
"label": "Education",
"key": "education",
"required": true,
"options": [
{
"label": "High School Diploma",
"value": "high_school"
},
{
"label": "Associate Degree",
"value": "associate"
},
{
"label": "Bachelor's Degree",
"value": "bachelor"
},
{
"label": "Doctoral Degree (Ph.D.)",
"value": "doctor"
},
{
"label": "Other",
"value": "other"
}
],
"defaultValue": ""
},
{
"type": "multi-select",
"label": "Make you chocie",
"key": "option",
"required": true,
"options": [
{
"label": "Option1",
"value": "1"
},
{
"label": "Option2",
"value": "2"
},
{
"label": "Option3",
"value": "3"
}
],
"defaultValues": ["1", "2"]
}
]
}
}
}
}
}
}
Article
{
"type": "article",
"value": {
"title": "your title",
"content": "This text is HTML",
"style": "multi-sources",
"sources": [
{
"label": "reference 1",
"title": "this is reference 1",
"content": "HTML content",
"url": "https://example.com/link"
},
{
"label": "reference 2",
"title": "this is reference 2",
"content": "HTML content",
"url": "https://example.com/link"
}
]
}
}
| Field | Required | Value | Description | Limitation |
|---|
title | No | String | | Maximum text 160 characters. |
content | No | String | Standard HTML format | Maximum text length: 1024 characters.For front-end displaysingle-source - Approximately 200 characters (8 lines) are displayed, the rest can be read in the overlay.multi-source - 1024 characters. |
style | No | String | Available valuessingle-source``multi-sourcesWhen sources's size == 1:single-source the UI will show a label, like "Read more".When source size > 1, multi-sources，the UI will show multiple buttons. | |
sources | No | List | refer to Article Source | Maximum size: 20. |
expandSources | No | Boolean | Default value is false. Only effective in multi-sources. When the value is true, the default sources' button is expanded. | |
Source
| Field | Required | Value | Description | Limitation |
|---|
title | No | String | The button label. Effective only for multi-sources. | Maximum length：200 characters. The front-end display truncates after 4 lines. |
content | No | String | Standard HTML format. | Maximum length: 4096 characters. |
url | No | String | The article link. | Maximum length: 1024 characters. |
readFullArticleLabel | No | String | The source article's link label.If not set, the default is "Read Full Article". | |
SetVariables
{
"type": "action",
"value": {
"action": "setVariables",
"data": {
"variables": [
{
"name": "global_system.Engagement.language",
"value": "en-us"
},
{
"name": "global_custom.CoreSegment.type",
"value": "core"
}
]
}
}
}
Type is action.
| Field | Required | Value | Description | Limitation |
| ----------- | -------- | ------ | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------ |
| action | Yes | String | The action type | For this case is setVariables | For this case is setVariables| |data | Yes | JSON | The action payload | |
| variables | Yes | List | The variables you need to change | Maximum size: 20 |
| name | Yes | String | The variable name. | The variable name's details are set in Contact Center flow editor and preference variable setting. |
| value | Yes | String | All string is good, Contact Center does the validation based on its variable type. | Maximum length: 1024 characters |
Parameters in response to DialogFlow
Contexts
Contact Center adds a context in every detectIntect request to DialogFlow called
zcc-engagement-context. It contains a list of parameters collected by Contact Center.
{
"name": "projects/your-project-id/agent/sessions/unique-session-id/contexts/zcc-engagement-context",
"lifespanCount": 100,
"parameters": {
"engagementId": {
"stringValue": "b813576e-5301-4b0c-b448-cc09c32ed72a-0fffcc35",
"kind": "stringValue"
},
"consumerName": {
"stringValue": "Tom",
"kind": "stringValue"
}
}
}
Supported parameters and variables
Contact Center sets a specific DialogFlow context called zcc-engagement-context at the beginning of the conversation.
"outputContexts": [
{
"name": "other context if there is"
...
},
{
"lifespanCount": 99,
"name": "zcc-engagement-context",
"parameters": {
"global_system.Engagement.timezone": "America/New_York",
"global_system.Engagement.regionCode": "GA",
"global_system.Consumer.email": "a@q.com",
"global_system.Engagement.latLong": "34.0409, -84.0237",
"global_custom.CustomerVariableGroup.QueueOpenHours": "1698872160000",
"global_custom.CustomerVariableGroup.CVariable001": "this is default value",
"global_system.Engagement.locale": "en-us",
"global_custom.Website_Data_Value.GJavescriptVariable_hostname": "localhost",
"global_system.Engagement.regionName": "Georgia",
"global_system.Engagement.cityName": "Suwanee",
"global_system.Consumer.consumerId": "hArHu1F-RyO0N7ghKo9KuA",
"global_system.Engagement.startTime": "1727343201778",
"global_custom.eva_zcc_g1.eva_zcc_va1": "5",
"global_system.Consumer.preferredName": "a",
"global_custom.CustomerVariableGroup.boolenVariable": "false",
"global_system.Engagement.countryName": "United States",
"global_system.Engagement.ipAddress": "66.172.49.116",
"global_custom.eee.satisfy": "满意",
"global_custom.GeorgeCustVars.DateTimeVar": "1714406400000",
"global_system.Engagement.countryCode": "US",
"global_custom.CustomerVariableGroup.CustomeURL": "https://zoom.us",
"global_system.Engagement.device": "Desktop",
"global_system.Engagement.startPageTitle": "Chat Demo",
"global_system.Engagement.authenticationStatus": "false",
"global_system.Engagement.engagementId": "WIRvdlvJQ2-nY_JvWQqs1Q",
"global_custom.CustomerVariableGroup.skyy0830-2": "5000",
"global_system.Engagement.continentCode": "NA",
"global_custom.GeorgeCustVars.AgentVar": "george.sun+qa+cci+agent02@test.zoom.us",
"global_custom.keal-test.abc-123": "skyytest1205@grr.la",
"global_custom.CustomerVariableGroup.skyy0830": "This is default value of skyy0830",
"global_custom.Website_Data_Value.Query_Parameter_apikey": "aQtv0t6-QZSQiAu1okfZkg",
"global_system.Engagement.postalCode": "30024",
"global_system.Engagement.continentName": "North America",
"global_custom.keal-test.percentVariable": "52",
"global_system.Engagement.browser": "Chrome",
"global_system.Engagement.operatingSystem": "macOS",
"global_custom.Website_Data_Value.Cookie_zm_lang": "en-US",
"global_custom.CustomerVariableGroup.CVariable002": "true",
"global_system.Engagement.startPage": "http://localhost:3000/?key=fpHtQa0XRkuRekplmGHkpA&env=qa&apikey=aQtv0t6-QZSQiAu1okfZkg&type=chat",
"global_system.Account.availability": "true",
"global_custom.GeorgeCustVars.QueueuVar": "SMS01-George"
}
}
]
All the global variables in Contact Center are in the parameters field, and we have already filtered the
variables with empty values.
Payload
{
"action": "formSumit",
"data": {
"interactionId": "a806116e-5301-4b0c-b448-cc09c32ed72a-0fffcb44",
"interacted": false,
"values": [
{
"key": "name",
"type": "textInput",
"value": "Tom"
},
{
"key": "education",
"type": "select",
"value": "bachelor"
},
{
"key": "option",
"type": "multi-select",
"value": ["1", "2"]
}
],
"originMessage": {
"type": "form",
"value": {
"title": "your title",
"description": "<p>I really like using Markdown.</p> ",
"fields": [
{
"type": "textInput",
"label": "Name",
"key": "name",
"required": true,
"defaultValue": ""
},
{
"type": "select",
"label": "Education",
"key": "education",
"required": true,
"options": [
{
"label": "High School Diploma",
"value": "high_school"
},
{
"label": "Associate Degree",
"value": "associate"
},
{
"label": "Bachelor's Degree",
"value": "bachelor"
},
{
"label": "Doctoral Degree (Ph.D.)",
"value": "doctor"
},
{
"label": "Other",
"value": "other"
}
],
"defaultValue": ""
},
{
"type": "multi-select",
"label": "Make you chocie",
"key": "option",
"required": true,
"options": [
{
"label": "Option1",
"value": "1"
},
{
"label": "Option2",
"value": "2"
},
{
"label": "Option3",
"value": "3"
}
],
"defaultValues": ["1", "2"]
}
]
}
}
}
}
| Field | Value | Description |
|---|
| action | String | formSubmit``optionSubmit |
| data | JSON | |
optionSubmit
| Field | Value | Description |
|---|
interactionId | String | The QuickReply or Card's uniqueId. |
interacted | Boolean | If the consumer didn't click any buttons, this value is set to false. |
value | String | The identified value that the consumer selected. |
optionIndex | Int | If it's a Carousel message, this will be the card index. |
originMessage | JSON | The origin QuickReply or Card or Carousel message. |
formSubmit
| Field | Value | Description |
|---|
interactionId | String | The form's uniqueId. |
interacted | Boolean | If the consumer selected Back without submitting, this value is set to false. |
values | List | The identified values that the consumer submitted. |
originMessage | JSON | The origin Form message. |