# 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
```json
{
"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
```json
{
"type": "html",
"value": "Please type your query below \n\nTo connect with Customer Care Team / Live Agent type \"Contact us\"
To access case management and contact our support team, enter \"Contact Us\"
"
}
```
| Field | Required | Value | Description | Limitation |
| ------- | -------- | ------ | -------------------- | ------------------------------------- |
| `value` | Yes | String | Standard HTML format | Maximum text length: 4096 characters. |
### Markdown
```json
{
"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
```json
{
"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`)
```json
{
"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
```json
{
"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`)
```json
{
"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
```json
{
"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
```json
{
"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
```json
{
"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 rule`email`, must be in email address format`integer`, require input of positive integers.`decimal`, require decimal input`custom`, 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
```json
{
"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
```json
{
"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
```json
{
"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
```json
{
"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`)
```json
{
"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": "I really like using Markdown.
",
"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
```json
{
"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 display**`single-source` - Approximately 200 characters (8 lines) are displayed, the rest can be read in the overlay.`multi-source` - 1024 characters. |
| `style` | No | String | **Available values**`single-source``multi-sources`When `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`
```json
{
"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.
```json
{
"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.
```json
"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
```json
{
"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": "I really like using Markdown.
",
"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. |