MENU
      Open

        Open


        Article summary

        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:

        MethodURI
        POSTAPI 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.

        FieldTypeRequiredDescription
        versionStringOptionalChatbot version
        • v1 | v2 (default)
          • Set to v1 when not entered
        userIdStringRequiredUnique chatbot user ID
        • Any input up to 256 characters
        userIpStringOptionalUser IP address
        timestampLongRequiredArbitrary timestamp value (timestamp)
        bubblesArrayRequiredEmpty array or 1 Text component created with the Welcome component
        eventStringRequiredEvent value
        • Set to open

        bubble

        The following describes bubble.

        FieldTypeRequiredDescription
        typeStringRequiredComponent type
        dataObjectRequiredComponent configuration information
        data.descriptionStringRequiredDetailed 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"
        }
        JSON

        Response

        The following describes the response format.

        Response body

        The following describes the response body.

        FieldTypeRequiredDescription
        versionStringOptionalChatbot version
        • v1 | v2
          • Respond with v1 if not entered on request
        userIdStringRequiredUnique chatbot user ID
        • Same as the userId value set on request
        timestampLongRequiredTimestamp value (timestamp)
        bubblesArrayRequiredbubbles details
        • Array of response components
        • Each component is matched with a response bubble in the chatbot
        entitiesArrayOptionalChatbot entity analysis results that matched the user's query
        persistentMenuObjectOptionalPersistent menu information
        keywordsArrayOptionalkeywords details
        • exactMatch | contain
          • exactMatch: User input matches keywords
          • contain: User input contains keywords
        conversationObjectOptionalConversation configuration information
        conversation.scenarioNameStringConditionalScenario name
        conversation.chatUtteranceSetIdStringConditionalConversation utterance ID
        conversation.typesArrayConditionalConversation type
        codeStringConditionalError code
        • It is displayed when a chatbot query fails
        • 500
        messageStringConditionalError message
        • It is displayed when a chatbot query fails
        • Internal server error
        timestampStringConditionalError time (timestamp)
        • It is displayed when a chatbot query fails
        eventStringRequiredEvent value

        bubbles

        The following describes bubbles.

        FieldTypeRequiredDescription
        typeStringRequiredComponent type
        dataObjectOptionalComponent configuration information
        data.descriptionStringConditionalDetailed Descriptions of Components
        informationArrayOptionalinformation details

        information

        The following describes bubbles.information.

        FieldTypeRequiredDescription
        keyStringConditionalData key
        valueStringConditionalData value

        keywords

        The following describes keywords.

        FieldTypeRequiredDescription
        keywordStringConditionalKeywords
        groupStringConditionalKeyword group
        typeStringConditionalKeyword 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"
        }
        JSON

        Was this article helpful?

        Changing your password will log you out immediately. Use the new password to log back in.
        First name must have atleast 2 characters. Numbers and special characters are not allowed.
        Last name must have atleast 1 characters. Numbers and special characters are not allowed.
        Enter a valid email
        Enter a valid password
        Your profile has been successfully updated.