--- title: "Open" slug: "ai-application-service-chatbot-open" tags: ["CLOVA Chatbot"] updated: 2026-09-17T09:15:53Z published: 2026-09-17T09:15:53Z canonical: "api.ncloud-docs.com/ai-application-service-chatbot-open" --- > ## Documentation Index > Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # Open Classic/VPC 환경에서 이용 가능합니다. 챗봇에 웰컴 메시지가 설정되어 있는 경우 API를 호출했을 때 자동으로 웰컴 메시지를 응답합니다. 참고 챗봇 답변의 응답 컴포넌트는 다음 3가지 형태의 컴포넌트를 제공합니다. - Basic Component - Composite Component - Flex Component - 컴포넌트에 대한 자세한 내용은 [Basic 컴포넌트 상세 정보](/docs/ai-application-service-chatbot-basic), [Composite 컴포넌트 상세 정보](/docs/ai-application-service-chatbot-composite), [Flex 컴포넌트 상세 정보](/docs/ai-application-service-chatbot-flex)를 참조해 주십시오. ## 요청 요청 형식을 설명합니다. 요청 형식은 다음과 같습니다. | 메서드 | URI | | --- | --- | | POST | CLOVA Chatbot 빌더에서 생성된 API Gateway의 고유 InvokeURL | ### 요청 헤더 CLOVA Chatbot API에서 공통으로 사용하는 헤더에 대한 정보는 [CLOVA Chatbot 요청 헤더](/docs/ai-application-service-chatbot#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)를 참조해 주십시오. ### 요청 바디 요청 바디에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `version` | String | Optional | 챗봇 버전 - `v1` \| `v2` (기본값) - 미입력 시 `v1` 설정 | | `userId` | String | Required | 챗봇 사용자 고유 아이디 - 최대 256자 이내 임의 입력 | | `userIp` | String | Optional | 사용자 IP 주소 | | `timestamp` | Long | Required | 임의의 타임 스탬프 값(Timestamp) | | `bubbles` | Array | Required | 비어 있는 배열 또는 [Welcome 컴포넌트](/docs/ai-application-service-chatbot-action#Welcome%EC%BB%B4%ED%8F%AC%EB%84%8C%ED%8A%B8)로 생성된 1개의 [Text 컴포넌트](/docs/ai-application-service-chatbot-basic#Text%EC%BB%B4%ED%8F%AC%EB%84%8C%ED%8A%B8) - [bubbles 상세 정보](/docs/ai-application-service-chatbot-open#bubble) 참조 | | `event` | String | Required | 이벤트 값 - `open`으로 설정 | #### `bubble` `bubble`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `type` | String | Required | 컴포넌트 유형 - `text` \| `image` \| `button` \| `template` \| `carousel` \| `flex` \| `line_sticker` \| `lineworks_sticker` \| - 각 컴포넌트에 대한 자세한 내용은 [Basic 컴포넌트 상세 정보](/docs/ai-application-service-chatbot-basic), [Composite 컴포넌트 상세 정보](/docs/ai-application-service-chatbot-composite), [Flex 컴포넌트 상세 정보](/docs/ai-application-service-chatbot-flex) 참조 | | `data` | Object | Required | 컴포넌트 구성 정보 | | `data.description` | String | Required | 컴포넌트 상세 설명 | ### 요청 예시 요청 예시는 다음과 같습니다. ``` { "version": "v2", "userId": "{userId}", "userIp": "{userIp}", "timestamp": 12345678, "bubbles": [ { "type": "text", "data" : { "description" : "postback text of welcome action" } } ], "event": "open" } ``` ## 응답 응답 형식을 설명합니다. ### 응답 바디 응답 바디에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `version` | String | - | 챗봇 버전 - `v1` \| `v2` - 요청 시 입력하지 않으면 `v1`으로 응답됨 | | `userId` | String | - | 챗봇 사용자 고유 아이디 - 요청 시 설정한 `userId` 값과 동일 | | `timestamp` | Long | - | 타임 스탬프 값(Timestamp) | | `bubbles` | Array | - | bubbles 상세 정보: [bubbles](/docs/ai-application-service-chatbot-open#bubbles) - 응답 컴포넌트의 배열 - 각 컴포넌트는 챗봇의 응답 버블(Bubble)과 매치됨 | | `entities` | Array | - | 사용자의 질의에 일치된 챗봇 엔티티 (Entity) 분석 결과 | | `persistentMenu` | Object | - | 고정 메뉴(Persistent Menu) 정보 - 자세한 설명은 [PersistentMenu 컴포넌트](/docs/ai-application-service-chatbot-composite#PersistentMenu%EC%BB%B4%ED%8F%AC%EB%84%8C%ED%8A%B8) 참조 | | `keywords` | Array | - | keywords 상세 정보: [keywords](/docs/ai-application-service-chatbot-open#keywords) - `exactMatch` \| `contain` - `exactMatch`: 사용자 입력 값과 키워드가 일치 - `contain`: 사용자 입력 값에 키워드가 포함 | | `conversation` | Object | - | 대화 구성 정보 | | `conversation.scenarioName` | String | - | 시나리오 이름 | | `conversation.chatUtteranceSetId` | String | - | 대화 발화 아이디 | | `conversation.types` | Array | - | 대화 유형 | | `code` | String | - | 오류 코드 - 챗봇 질의에 실패했을 경우 표시 - `500` | | `message` | String | - | 오류 메시지 - 챗봇 질의에 실패했을 경우 표시 - `Internal server error` | | `timestamp` | String | - | 응답 시간(Timestamp) - 챗봇 질의에 실패했을 경우 표시 | | `event` | String | - | 이벤트 값 | #### `bubbles` `bubbles`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `type` | String | - | 컴포넌트 유형 - `text` \| `image` \| `button` \| `template` \| `carousel` \| `flex` \| `line_sticker` \| `lineworks_sticker` \| - 각 컴포넌트에 대한 자세한 내용은 [Basic 컴포넌트 상세 정보](/docs/ai-application-service-chatbot-basic), [Composite 컴포넌트 상세 정보](/docs/ai-application-service-chatbot-composite), [Flex 컴포넌트 상세 정보](/docs/ai-application-service-chatbot-flex) 참조 | | `data` | Object | - | 컴포넌트 구성 정보 | | `data.description` | String | - | 컴포넌트 상세 설명 | | `information` | Array | - | information 상세 정보: [information](/docs/ai-application-service-chatbot-open#information) | #### `information` `information`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `key` | String | - | 데이터 키 | | `value` | String | - | 데이터 값 | #### `keywords` `keywords`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `keyword` | String | - | 키워드 | | `group` | String | - | 키워드 그룹 | | `type` | String | - | 키워드 종류 | ### 응답 상태 코드 CLOVA Chatbot API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 [CLOVA Chatbot 응답 상태 코드](/docs/ai-application-service-chatbot#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C)를 참조해 주십시오. ### 응답 예시 응답 예시는 다음과 같습니다. ``` { "version":"v2", "userId":"{userId}", "timestamp":1725842214334, "bubbles":[ { "type":"text", "data":{ "description":"안녕하세요.\n궁금한 점을 챗봇에게 물어보세요." }, "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" } ```