Open

Prev Next

Available in Classic and VPC

If the chatbot has a welcome message set up, it will automatically respond with a welcome message when the API is called.

Note

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

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 Empty array or 1 Text component created with the Welcome component
event String Required Event value
  • Set to open

bubble

The following describes bubble.

Field Type Required Description
type String Required Component type
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" : "postback text of welcome action" 
        }
    } 
],
"event": "open"
}

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
timestamp Long Required Timestamp value (timestamp)
bubbles Array Required bubbles details
  • Array of response components
  • Each component is matched with a response bubble in the chatbot
entities Array Optional Chatbot entity analysis results that matched the user's query
persistentMenu Object Optional Persistent menu information
keywords Array Optional keywords details
  • exactMatch | contain
    • exactMatch: User input matches keywords
    • contain: User input contains keywords
conversation Object Optional Conversation configuration information
conversation.scenarioName String Conditional Scenario name
conversation.chatUtteranceSetId String Conditional Conversation utterance ID
conversation.types Array Conditional Conversation type
code String Conditional Error code
  • It is displayed when a chatbot query fails
  • 500
message String Conditional Error message
  • It is displayed when a chatbot query fails
  • Internal server error
timestamp String Conditional Error time (timestamp)
  • It is displayed when a chatbot query fails
event String Required Event value

bubbles

The following describes bubbles.

Field Type Required Description
type String Required Component type
data Object Optional Component configuration information
data.description String Conditional Detailed Descriptions of Components
information Array Optional information details

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.

{
    "version":"v2",
    "userId":"{userId}",
    "timestamp":1725842214334,
    "bubbles":[
        {
        "type":"text",
        "data":{
            "description":"Hello.\nAsk any questions to the chatbot."
            },
            "information":[
                {"key":"chatType", "value":"TEXT"},
                {"key":"chatType", "value":"TEXT"},
                {"key":"defaultMsgType", "value":"welcomeMsg"},
                {"key":"welcomeMsgId", "value":"20727"},
                {"key":"endOfBubble", "value":"endOfBubble"}
            ]
        }
    ],
    "entities":[],
    "persistentMenu":
    {
        "type":"template",
        "title":"PersistentMenu",
        "data":
        {
            "contentTable":[
                [
                    {
                        "rowSpan":1,
                        "colSpan":1,
                        "data":
                            {
                                "type":"button",
                                "title":"PersistentMenu1",
                                "subTitle":"",
                                "data":
                                    {
                                        "type":"basic",
                                        "action":
                                            {
                                                "type":"utterance",
                                                "data":
                                                    {
                                                        "utteranceId":5560752,
                                                        "text":"PersistentMenu1",
                                                        "postback":"_U_5560752"
                                                    }
}}}}]]}},
    "keywords":[],
    "conversation":
        {
            "scenarioName":null,
            "chatUtteranceSetId":null,
            "types":[]
        },
    "event":"open"
}