Send

English

Send

Article summary

Did you find this summary helpful?

Thank you for your feedback

Available in Classic and VPC

Send questions to the chatbot.

Note

The following three types of response components are available for chatbot answers.

Basic Component
Composite Component
Flex Component
For more information about components, see Basic component details, Composite component details, and Flex component details.

Request

The following describes the request format for the endpoint. The request format is as follows:

Method	URI
POST	API Gateway's unique invoke URL created in CLOVA Chatbot Builder

Request headers

For headers common to all CLOVA Chatbot Custom APIs, see Common CLOVA Chatbot Custom API headers.

Request body

The following describes the request body.

Field	Type	Required	Description
`version`	String	Optional	Chatbot version `v1` \| `v2` (default) Set to `v1` when not entered
`userId`	String	Required	Unique chatbot user ID Any input up to 256 characters
`userIp`	String	Optional	User IP address
`timestamp`	Long	Required	Arbitrary timestamp value (timestamp)
`bubbles`	Array	Required	Support for only 1 text component See Text component for more information If there is more than one `text` component, use the last one See bubbles details
`event`	String	Required	Event value Set to `send`

`bubble`

The following describes bubble.

Field	Type	Required	Description
`type`	String	Required	Component type `text` \| `image` \| `button` \| `template` \| `carousel` \| `flex` \| `line_sticker` \| `lineworks_sticker` \| For more information each component, see Basic component details, Composite component details, and Flex component details
`data`	Object	Required	Component configuration information
`data.description`	String	Required	Detailed Descriptions of Components

Request example

The following is a sample request.

{
"version": "v2",
"userId": "{userId}",
"userIp": "{userIp}",
"timestamp": 12345678,
"bubbles": [ 
    {
        "type": "text",
        "data" : { 
            "description" : "How do I access the CLOVA Chatbot service from the console?" 
        } 
    } 
],
"event": "send"
}

Response

The following describes the response format.

Response body

The following describes the response body.

Field	Type	Required	Description
`version`	String	Optional	Chatbot version `v1` \| `v2` Respond with `v1` if not entered on request
`userId`	String	Required	Unique chatbot user ID Same as the `userId` value set on request
`sessionId`	String	Optional	Current session ID It is managed by CLOVA Chatbot
`timestamp`	Long	Required	Timestamp value (ms)
`bubbles`	Array	Optional	bubbles details Array of response components Each component is matched with a response bubble in the chatbot
`scenario`	Object	Optional	Scenario information Scenario analysis results matching the user's query The scenario name and intent (conversation type) are provided
`scenario.name`	String	Conditional	Scenario name
`scenario.chatUtteranceSetId`	Long	Conditional	Scenario utterance type ID
`scenario.intent`	Array	Conditional	Scenario intent (conversation type)
`entities`	Array	Optional	Chatbot entity analysis results that matched the user's query
`quickButtons`	Array	Optional	Information about the pinned buttons set at the bottom of the chatbot See Quick buttons details for more information
`keywords`	Array	Optional	keywords details `exactMatch` \| `contain` `exactMatch`: User input matches keywords `contain`: User input contains keywords
`conversation`	Object	Optional	Conversation information
`conversation.scenarioName`	String	Conditional	Scenario name
`conversation.chatUtteranceSetId`	Long	Conditional	Conversation utterance type ID
`conversation.types`	Array	Conditional	Conversation type
`normalizer`	String	Optional	System entity that matched the user's query
`event`	String	Required	Event value

`bubbles`

The following describes bubbles.

Field	Type	Required	Description
`type`	String	Required	Component type `text` \| `image` \| `button` \| `template` \| `carousel` \| `flex` \| `line_sticker` \| `lineworks_sticker` \| For more information each component, see Basic component details, Composite component details, and Flex component details
`title`	String	Optional	Component name
`data`	Object	Optional	Component configuration information
`data.description`	String	Conditional	Detailed Descriptions of Components
`data.url`	String	Conditional	URL address
`data.urlAlias`	String	Conditional	URL alias
`data.packageId`	String	Conditional	LINE Sticker package ID Used only in LINE Sticker component
`data.stickerId`	String	Conditional	LINE Sticker sticker ID Used only in LINE Sticker component
`information`	Array	Optional	information details
`context`	Array	Optional	Component context information

`information`

The following describes bubbles.information.

Field	Type	Required	Description
`key`	String	Conditional	Data key
`value`	String	Conditional	Data value

`keywords`

The following describes keywords.

Field	Type	Required	Description
`keyword`	String	Conditional	Keywords
`group`	String	Conditional	Keyword group
`type`	String	Conditional	Keyword type

Response status codes

For response status codes common to all CLOVA Chatbot Custom APIs, see Common CLOVA Chatbot Custom API response status codes.

Response example

The following is a sample example.

Default answer

The following is a sample response for a default answer.

{
  "version": "v2",
  "userId": "{userId}",
  "timestamp": 1664169457884,
  "bubbles": [
    {
      "type": "text",
      "data": {
        "description": "Chatbot Answer",
        "url": "https://ncloud.com", // optional : URL
        "urlAlias": "https://ncloud.com" // optional : URL
      },
      "information": [
        {
          "key": "chatType",
          "value": "TEXT"
        },
        {
          "key": "chatType",
          "value": "TEXT"
        },
        {
          "key": "score",
          "value": "1.0"
        },
        {
          "key": "scenarioName",
          "value": "Conversation Name"
        },
        {
          "key": "endOfBubble",
          "value": "endOfBubble"
        },
        {
          "key": "matchingType",
          "value": "exactMatch"
        },
        {
          "key": "domainCode",
          "value": "Domain Code"
        }
      ],
      "context": []
    }
  ],
  "scenario": {
    "name": "Conversation Name",
    "chatUtteranceSetId": 4929383, // Conversation utterance ID (Conversation ID)
    "intent": []
  },
  "entities": [],
  "keywords": [],
  "conversation": {
    "scenarioName": "Conversation Name",
    "chatUtteranceSetId": 4929383, // Conversation utterance ID (Conversation ID)
    "types": []
  },
  "normalizer": "null",
  "event": "send"
}

Image answer

The following is a sample response for an image answer.

{
  "version": "v2",
  "userId": "{userId}",
  "timestamp": 1664170469355,
  "bubbles": [
    {
      "type": "carousel",
      "data": {
        "cards": [
          {
            "type": "template",
            "data": {
              "cover": {
                "type": "image",
                "data": {
                  "imageUrl": "https://clovachatbot.ncloud.com/i48103278ci6f6-9f51-4d08-a947-1c8acc992629",
                  "imagePosition": "top",
                  "action": {
                    "type": "link",
                    "data": {
                      "url": "https://ncloud.com"
                    }
                  }
                }
              }
            }
          }
        ]
      }
    }
  ],
  "scenario": {
    "name": "Conversation Name",
    "chatUtteranceSetId": 4929385, // Conversation utterance ID (Conversation ID)
    "intent": []
  },
  "entities": [],
  "keywords": [],
  "conversation": {
    "scenarioName": "Conversation Name",
    "chatUtteranceSetId": 4929385, // Conversation utterance ID (Conversation ID)
    "types": []
  },
  "normalizer": "null",
  "event": "send"
}

Image + text answer

The following is a sample response for an image + text answer.

{
  "version": "v2",
  "userId": "{userId}",
  "timestamp": 1664170681849,
  "bubbles": [
    {
      "type": "carousel",
      "data": {
        "cards": [
          {
            "type": "template",
            "data": {
              "cover": {
                "type": "image",
                "title": "image title",
                "data": {
                  "imageUrl": "https://clovachatbot.ncloud.com/i48103278ci6f6-9f51-4d08-a947-1c8acc992629",
                  "description": "image description"
                }
              },
              "contentTable": [
                [
                  {
                    "rowSpan": 1,
                    "colSpan": 1,
                    "data": {
                      "type": "button",
                      "title": "display button1 name",
                      "data": {
                        "type": "basic",
                        "action": {
                          "type": "link",
                          "data": {
                            "url": "https://ncloud.com"
                          }
                        }
                      }
                    }
                  }
                ],
                [
                  {
                    "rowSpan": 1,
                    "colSpan": 1,
                    "data": {
                      "type": "button",
                      "title": "display button2 name",
                      "data": {
                        "type": "basic",
                        "action": {
                          "type": "link",
                          "data": {
                            "url": "https://fin-ncloud.com"
                          }
                        }
                      }
                    }
                  }
                ]
              ]
            },
            "information": [
              {
                "key": "carousel",
                "value": "1"
              },
              {
                "key": "chatType",
                "value": "IMAGECARD"
              },
              {
                "key": "imageOnly",
                "value": "false"
              },
              {
                "key": "chatType",
                "value": "IMAGECARD"
              },
              {
                "key": "score",
                "value": "1.0"
              },
              {
                "key": "scenarioName",
                "value": "Conversation Name"
              },
              {
                "key": "matchingType",
                "value": "exactMatch"
              },
              {
                "key": "domainCode",
                "value": "Domain Code"
              }
            ],
            "context": []
          }
        ]
      }
    }
  ],
  "scenario": {
    "name": "Conversation Name",
    "chatUtteranceSetId": 4929386, // Conversation utterance ID (Conversation ID)
    "intent": []
  },
  "entities": [],
  "keywords": [],
  "conversation": {
    "scenarioName": "Conversation Name",
    "chatUtteranceSetId": 4929386, // Conversation utterance ID (Conversation ID)
    "types": []
  },
  "normalizer": "null",
  "event": "send"
}

Multi-link answer

The following is a sample response for a multi-link answer.

{
  "version": "v2",
  "userId": "{userId}",
  "timestamp": 1664171090887,
  "bubbles": [
    {
      "type": "template",
      "data": {
        "cover": {
          "type": "text",
          "data": {
            "description": "Chatbot Answer"
          }
        },
        "contentTable": [
          [
            {
              "rowSpan": 1,
              "colSpan": 1,
              "data": {
                "type": "button",
                "title": "Button Name",
                "data": {
                  "type": "basic",
                  "action": {
                    "type": "link",
                    "data": {
                      "url": "https://ncloud.com"
                    }
                  }
                }
              }
            }
          ]
        ]
      },
      "information": [
        {
          "key": "chatType",
          "value": "MULTILINKS"
        },
        {
          "key": "chatType",
          "value": "MULTILINKS"
        },
        {
          "key": "score",
          "value": "1.0"
        },
        {
          "key": "scenarioName",
          "value": "Conversation Name"
        },
        {
          "key": "endOfBubble",
          "value": "endOfBubble"
        },
        {
          "key": "matchingType",
          "value": "exactMatch"
        },
        {
          "key": "domainCode",
          "value": "Domain Code"
        }
      ],
      "context": []
    }
  ],
  "scenario": {
    "name": "Conversation Name",
    "chatUtteranceSetId": 4929384, // Conversation utterance ID (Conversation ID)
    "intent": []
  },
  "entities": [],
  "keywords": [],
  "conversation": {
    "scenarioName": "Conversation Name",
    "chatUtteranceSetId": 4929384, // Conversation utterance ID (Conversation ID)
    "types": []
  },
  "normalizer": "null",
  "event": "send"
}

Form V1 (multiple-choice) answer

The following is a sample response for a Form V1 (multiple-choice) answer.

{
  "version": "v2",
  "userId": "{userId}",
  "timestamp": 1664171277095,
  "bubbles": [
    {
      "type": "template",
      "data": {
        "cover": {
          "type": "text",
          "data": {
            "description": "Chatbot Answer"
          }
        },
        "contentTable": [
          [
            {
              "rowSpan": 1,
              "colSpan": 1,
              "data": {
                "type": "button",
                "title": "Button Name", // Use this value if you want the button name to be displayed.
                "data": {
                  "type": "basic",
                  "action": {
                    "type": "postback",
                    "data": {
                      "postback": "Button Name",
                      "postbackFull": "_T_Button Name" // Use this value if you want a button action.
                    }
                  }
                }
              }
            }
          ]
        ]
      },
      "information": [
        {
          "key": "imageOnly",
          "value": "false"
        },
        {
          "key": "chatType",
          "value": "SINGLEFORM"
        },
        {
          "key": "chatType",
          "value": "SINGLEFORM"
        },
        {
          "key": "score",
          "value": "1.0"
        },
        {
          "key": "scenarioName",
          "value": "Conversation Name"
        },
        {
          "key": "endOfBubble",
          "value": "endOfBubble"
        },
        {
          "key": "matchingType",
          "value": "exactMatch"
        },
        {
          "key": "domainCode",
          "value": "Domain Code"
        },
        {
          "key": "formStart",
          "value": "true"
        },
        {
          "key": "serviceLinkedToForm",
          "value": ""
        }
      ],
      "context": []
    }
  ],
  "scenario": {
    "name": "Conversation Name",
    "chatUtteranceSetId": 4929388, // Conversation utterance ID (Conversation ID)
    "intent": []
  },
  "entities": [],
  "keywords": [],
  "conversation": {
    "scenarioName": "Conversation Name",
    "chatUtteranceSetId": 4929388, // Conversation utterance ID (Conversation ID)
    "types": []
  },
  "normalizer": "null",
  "event": "send"
}

Form V2 (multiple-choice) answer

The following is a sample response for a Form V2 (multiple-choice) answer.

{
  "version": "v2",
  "userId": "{userId}",
  "timestamp": 1664171884718,
  "bubbles": [
    {
      "type": "template",
      "data": {
        "cover": {
          "type": "text",
          "data": {
            "description": "Chatbot Answer"
          }
        },
        "contentTable": [
          [
            {
              "rowSpan": 1,
              "colSpan": 1,
              "data": {
                "type": "button",
                "title": "Button Name",
                "data": {
                  "type": "basic",
                  "action": {
                    "type": "postback",
                    "data": {
                      "postback": "UnexpiredForm\u241e47952\u241e0",
                      "displayText": "Button Name", // Use this value if you want the button name to be displayed.
                      "postbackFull": "_T_UnexpiredForm\u241e47952\u241e0" // Use this value if you want a button action.
                    }
                  }
                }
              }
            }
          ]
        ]
      },
      "information": [
        {
          "key": "imageOnly",
          "value": "false"
        },
        {
          "key": "chatType",
          "value": "SINGLEFORM"
        },
        {
          "key": "chatType",
          "value": "SINGLEFORM"
        },
        {
          "key": "score",
          "value": "1.0"
        },
        {
          "key": "scenarioName",
          "value": "Conversation Name"
        },
        {
          "key": "endOfBubble",
          "value": "endOfBubble"
        },
        {
          "key": "matchingType",
          "value": "exactMatch"
        },
        {
          "key": "domainCode",
          "value": "Domain Code"
        },
        {
          "key": "formStart",
          "value": "true"
        }
      ],
      "context": []
    }
  ],
  "scenario": {
    "name": "Conversation Name",
    "chatUtteranceSetId": 4929389, // Conversation utterance ID (Conversation ID)
    "intent": []
  },
  "entities": [],
  "keywords": [],
  "conversation": {
    "scenarioName": "Conversation Name",
    "chatUtteranceSetId": 4929389, // Conversation utterance ID (Conversation ID)
    "types": []
  },
  "normalizer": "null",
  "event": "send"
}

Form V1 (quick reply) answer

The following is a sample response for a Form V1 (quick reply) answer.

{
  "version": "v2",
  "userId": "{userId}",
  "timestamp": 1664172269192,
  "bubbles": [
    {
      "type": "text",
      "data": {
        "description": "Chatbot Answer"
      },
      "information": [
        {
          "key": "imageOnly",
          "value": "false"
        },
        {
          "key": "chatType",
          "value": "SINGLEFORM"
        },
        {
          "key": "chatType",
          "value": "SINGLEFORM"
        },
        {
          "key": "score",
          "value": "1.0"
        },
        {
          "key": "scenarioName",
          "value": "Conversation Name"
        },
        {
          "key": "endOfBubble",
          "value": "endOfBubble"
        },
        {
          "key": "matchingType",
          "value": "exactMatch"
        },
        {
          "key": "domainCode",
          "value": "Domain Code"
        },
        {
          "key": "formStart",
          "value": "true"
        },
        {
          "key": "serviceLinkedToForm",
          "value": ""
        }
      ],
      "context": []
    }
  ],
  "scenario": {
    "name": "Conversation Name",
    "chatUtteranceSetId": 4929390, // Conversation utterance ID (Conversation ID)
    "intent": []
  },
  "entities": [],
  "quickButtons": [
    {
      "type": "button",
      "title": "Button Name",
      "data": {
        "type": "basic",
        "action": {
          "type": "postback",
          "data": {
            "postback": "Button Name",
            "postbackFull": "_T_Button Name" // Use this value if you want a button action.
          }
        }
      }
    }
  ],
  "keywords": [],
  "conversation": {
    "scenarioName": "Conversation Name",
    "chatUtteranceSetId": 4929390, // Conversation utterance ID (Conversation ID)
    "types": []
  },
  "normalizer": "null",
  "event": "send"
}

Form V2 (quick reply) answer

The following is a sample response for a Form V2 (quick reply) answer.

{
  "version": "v2",
  "userId": "{userId}",
  "timestamp": 1664172948306,
  "bubbles": [
    {
      "type": "text",
      "data": {
        "description": "Chatbot Answer"
      },
      "information": [
        {
          "key": "imageOnly",
          "value": "false"
        },
        {
          "key": "chatType",
          "value": "SINGLEFORM"
        },
        {
          "key": "chatType",
          "value": "SINGLEFORM"
        },
        {
          "key": "score",
          "value": "1.0"
        },
        {
          "key": "scenarioName",
          "value": "Conversation Name"
        },
        {
          "key": "endOfBubble",
          "value": "endOfBubble"
        },
        {
          "key": "matchingType",
          "value": "exactMatch"
        },
        {
          "key": "domainCode",
          "value": "Domain Code"
        },
        {
          "key": "formStart",
          "value": "true"
        }
      ],
      "context": []
    }
  ],
  "scenario": {
    "name": "Conversation Name",
    "chatUtteranceSetId": 4929393, // Conversation utterance ID (Conversation ID)
    "intent": []
  },
  "entities": [],
  "quickButtons": [
    {
      "type": "button",
      "title": "Button Name",
      "data": {
        "type": "basic",
        "action": {
          "type": "postback",
          "data": {
            "postback": "UnexpiredForm\u241e47954\u241e0",
            "displayText": "Button Name", // Use this value if you want the button name to be displayed.
            "postbackFull": "_T_UnexpiredForm\u241e47954\u241e0" // Use this value if you want a button action.
          }
        }
      }
    }
  ],
  "keywords": [],
  "conversation": {
    "scenarioName": "Conversation Name",
    "chatUtteranceSetId": 4929393, // Conversation utterance ID (Conversation ID)
    "types": []
  },
  "normalizer": "null",
  "event": "send"
}

Form open-ended answer

The following is a sample response for a Form open-ended answer.

{
  "version": "v2",
  "userId": "{userId}",
  "timestamp": 1665038738758,
  "bubbles": [
    {
      "type": "text",
      "data": {
        "description": "Chatbot Answer"
      },
      "information": [
        {
          "key": "chatType",
          "value": "TEXT"
        },
        {
          "key": "chatType",
          "value": "TEXT"
        },
        {
          "key": "score",
          "value": "1.0"
        },
        {
          "key": "scenarioName",
          "value": "Conversation Name"
        },
        {
          "key": "endOfBubble",
          "value": "endOfBubble"
        },
        {
          "key": "matchingType",
          "value": "exactMatch"
        },
        {
          "key": "domainCode",
          "value": "Domain Code"
        },
        {
          "key": "formStart",
          "value": "true"
        }
      ],
      "context": []
    }
  ],
  "scenario": {
    "name": "Conversation Name",
    "chatUtteranceSetId": 4929394, // Conversation utterance ID (Conversation ID)
    "intent": []
  },
  "entities": [],
  "keywords": [],
  "conversation": {
    "scenarioName": "Conversation Name",
    "chatUtteranceSetId": 4929394, // Conversation utterance ID (Conversation ID)
    "types": []
  },
  "normalizer": "null",
  "event": "send"
}

No-answer answer

The following is a sample response for a no-answer answer.

{
  "version": "v2",
  "userId": "{userId}",
  "timestamp": 1665972966091,
  "bubbles": [
    {
      "type": "text",
      "data": {
        "description": ""
      },
      "information": [
        {
          "key": "chatType",
          "value": "NOANSWER"
        },
        {
          "key": "chatType",
          "value": "NOANSWER"
        },
        {
          "key": "score",
          "value": "1.0"
        },
        {
          "key": "scenarioName",
          "value": "Conversation Name"
        },
        {
          "key": "endOfBubble",
          "value": "endOfBubble"
        },
        {
          "key": "matchingType",
          "value": "exactMatch"
        },
        {
          "key": "domainCode",
          "value": "Domain Code"
        }
      ],
      "context": []
    }
  ],
  "scenario": {
    "name": "Conversation Name",
    "chatUtteranceSetId": 4929395,
    "intent": []
  },
  "entities": [],
  "keywords": [],
  "conversation": {
    "scenarioName": "Conversation Name",
    "chatUtteranceSetId": 4929395,
    "types": []
  },
  "normalizer": "null",
  "event": "send"
}

LINE Flex

The following is a sample response for LINE Flex.

{
  "version": "v2",
  "userId": "{userId}",
  "sessionId": "{sessionId}",
  "timestamp": 12345678,
  "bubbles": [
    {
      "type": "flex",
      "title": "this is a flex message",
      "data" : {
        "type": "bubble",
        "hero": {
          "type": "image",
          "url": "https://scdn.line-apps.com/n/channel_devcenter/img/fx/01_1_cafe.png",
          "size": "full",
          "aspectRatio": "20:13",
          "aspectMode": "cover",
        },
        "body": {
          "type": "box",
          "layout": "vertical",
          "contents": [
            {
              "type": "text",
              "text": "Brown Cafe",
              "weight": "bold",
              "size": "xl"
            }
          ]
        },
        "footer": {
          "type": "box",
          "layout": "vertical",
          "spacing": "sm",
          "contents": [
            {
              "type": "button",
              "style": "link",
              "height": "sm",
              "action": {
                "type": "uri",
                "label": "CALL",
                "uri": "https://linecorp.com"
              }
            },
            {
              "type": "spacer",
              "size": "sm"
            }
          ],
          "flex": 0
        }
      }
    }
  ],
  "event": "send"
}

LINE Sticker

The following is a sample response for LINE Sticker.

{
  "type": "line_sticker",
  "data": {
    "packageId": "446",
    "stickerId": "1988"
  },
  "information": [
    {
      "key": "chatType",
      "value": "STICKER"
    },
    {
      "key": "chatType",
      "value": "STICKER"
    },
    {
      "key": "tagInfo",
      "value": "platformExactMatch=line"
    },
    {
      "key": "score",
      "value": "1.0"
    },
    {
      "key": "scenarioName",
      "value": "Conversation Name"
    },
    {
      "key": "endOfBubble",
      "value": "endOfBubble"
    },
    {
      "key": "matchingType",
      "value": "exactMatch"
    },
    {
      "key": "domainCode",
      "value": "Domain Code"
    }
  ],
  "context": [],
  "event": "send"
}

Was this article helpful?

What's Next

getPersistentMenu

Table of contents

Request
Response