외부 API

[Kakao 챗봇] 1. 주요 개념, 메모

swotato 2025. 9. 3. 14:33

참고

주요개념 | kakao business 비즈니스 가이드

kakaobusiness.gitbook.io

튜토리얼 | kakao business 비즈니스 가이드

kakaobusiness.gitbook.io

주요 개념

요약

개념	설명
인텐트 * Intent	사용자의 의도 - 인텐트를 표현하는 다양한 예시 문장을 대화문장(Utterance)이라고 칭한다.
발화 패턴	챗봇이 사용자 발화를 인식할 수 있도록 만드는 원리의 핵심 - 패턴을 잘 설정하면, 챗봇의 인텐트를 파악 능력을 향상시킬 수 있다. - 패턴 등록 과정 - 발화문을 등록한다. - 중요한 의미를 갖는 부분을 엔티티로 태깅한다.
엔티티 * Entity	봇이 이해할 수 있는 용어를 정리한 데이터 사전 - 엔티티가 정의되어 있다면, 봇은 사용자 발화로부터 사용자의 의도에 맞는 동작 수행을 위한 주요 데이터를 추출할 수 있다. - 특정 동작을 위한 트리거(단어)를 설정하는 데에 사용할 수 있다. - 엔티티 종류 - 시스템 엔티티: 챗봇 관리자 센터에서 미리 정의해둔 엔티티들 (날짜, 시간 등) - 사용자 엔티티: 엔티티명, 대표엔트리, 동의어를 설정해야 한다. 챗샘에서는 ‘mode’를 사용자 엔티티로 등록했다.
블록 *	인텐트(Intent)를 응대하는 가장 작은 단위 - 사용자 요청에 따른 동작을 수행한다. - 주요 기능 구성 - 사용자 발화 패턴, 파라미터, 봇 응답 형식, 스킬, 컨텍스트 - 블록 종류 - 기본 블록: 웰컴 블록, 폴백 블록, 탈출 블록, 인증 블록(플러그인 사용을 위한 블록) - 시나리오 블록
시나리오 * Scenario	봇 안에서 사용자가 경험할 수 있는 서비스 단위(= 미리 설계된 대화의 흐름) - 예시: ‘은행 챗봇'의 시나리오에는 ‘예금', ‘적금', ‘대출' 등이 존재할 수 있다. - 여러 블록의 집합이다. 즉, 다수의 블록들을 원하는 서비스 별로 그룹핑하여 편리하게 관리할 수 있다. - 시나리오 종류 - 기본 시나리오 - 커스텀 시나리오
스킬 * Skill	블록에 종속되어 사용자에게 응답을 돌려주는 기능 + 자체 api 서버 이용 - 스킬 적용 과정 - 챗봇 관리자센터에서 스킬을 생성한다. - 생성한 스킬 서버(자체 api 서버)의 엔드포인트를 등록한다.
파라미터 설정Parameter	파라미터 = 봇이 사용자의 의도를 정확히 이해하기 위해 필요로 하는 데이터 - API 형태로 구성된 스킬(Skil)은 데이터가 입력되면, 들어온 데이터에 맞는 다양한 결과값을 보내준다. 이때, 스킬에 보내지는 데이터 또한 파라미터이다. - 파라미터 구성 요소 - 파라미터 명 - 엔티티 - 값 - 엔티티 값: $로 시작하는 이름으로 구성된 값. 주로 파라미터 이름과 동일하게 사용 (예: $paramName1, $paramName2, …) - 특정 값: 값 위치에 # 으로 시작하는 이름으로 구성된 값. ex) #[current\|contextName].[path].[to] - 고정된 값: $이나 # 으로 시작하지 않는 값. 값 자체가 실제 파라미터의 값으로 사용된다. - 기본값: 필수 파라미터로 지정되지 않고 사용자의 발화나 이전 또는 현재의 특정 값을 참조하거나, 고정된 값이 설정되어 있지 않을 경우에 ‘기본 값’으로 채택해 사용되는 기본적인 값이다.
배포	수정 내용을 실제 서비스 중인 챗봇에 적용하는 것을 의미한다. 적용이 완료되기까지 약간의 시간이 소요될 수 있다.
봇 테스트	배포를 하기 전, 웹 상에서 봇을 테스트 할 수 있다. (페이지 우측 상단에 위치)

상세

사용자 발화 (Utterance)

사용자가 봇과 커뮤니케이션하기 위해 내뱉는 말 또는 텍스트 등을 의미한다.
사용자의 의도 인텐트를 표현하는 다양한 예시 문장을 대화 문장(Utterance)이라고 칭한다.

엔티티(Entity)

봇이 이해할 수 있는 용어를 체계적으로 정리한 데이터 사전을 의미한다.
엔티티가 정의되어 있다면, 봇은 사용자 발화로부터 사용자의 의도에 맞는 동작 수행을 위한 주요 데이터를 추출할 수 있다.
특정 동작을 위한 트리거(단어)를 설정하는 데에 사용할 수 있다.
엔티티 종류
- 시스템 엔티티: 챗봇 관리자 센터에서 미리 정의해둔 엔티티들 (날짜, 시간 등)
- 사용자 엔티티
  - 엔티티명, 대표엔트리, 동의어를 설정해야 한다.
  - 챗샘에서는 ‘mode’를 사용자 엔티티로 등록했다. (mode = “영한사전” | “영어 대화”)

블록(Block)

사용자 의도의 기본 단위. 인텐트(Intent) 라고도 부른다. 사용자 요청에 따른 동작을 수행한다.
1개의 블록은 1개의 의도를 표현한다.
주요 기능 구성
- 사용자 발화 패턴
- 파라미터
- 봇 응답 형식
- 스킬
- 컨텍스트
블록 종류
- 기본 블록
  - 웰컴 블록
  - 폴백 블록
    - 사용자의 발화 의도가 어떠한 블록과도 매칭이 되지 않을 때 (=봇이 사용자의 발화 의도를 이해하지 못할 때)의 응답을 설정하는 블록.
  - 탈출 블록
    - 봇의 되묻기 상황에서 사용자가 대화를 초기화하거나 탈출하고 싶을때 쓰는 사용자 명령어를 정의하는 블록.
  - 인증 블록
    - 플러그인 사용을 위한 블록.
    - 비즈니스 인증 필수.
- 시나리오 블록
  - 봇 작업자가 설계한대로 봇을 제작할 수 있는 일반적인 블록.
블록 작동 원리
- 사용자 발화를 기반으로, 화자의 의도에 해당하는 블록이 추출되고 출력으로 이어져 실행되는 모습

시나리오(Scenario)

봇 안에서 사용자가 경험할 수 있는 서비스 단위를 말한다. ‘미리 설계된 대화의 흐름’이다.
여러 블록의 집합이다. 즉, 다수의 블록들을 원하는 서비스 별로 그룹핑하여 편리하게 관리할 수 있다.
예시: ‘은행 챗봇'의 시나리오에는 ‘예금', ‘적금', ‘대출' 등이 존재할 수 있다.
시나리오 종류
- 기본 시나리오
- 커스텀 시나리오

발화 패턴

챗봇이 사용자 발화를 인식할 수 있도록 만드는 원리의 핵심.
패턴 등록 과정
- 발화문을 등록한다.
- 중요한 의미를 갖는 부분을 엔티티로 태깅한다.

스킬(Skill)

자체 API 서버를 구성하여, 이를 챗봇의 응답으로 사용할 수 있다.
블록에 종속되어 사용자에게 응답을 돌려준다.
사용 방법
- 스킬을 등록한다.
  - 스킬 응답을 처리하는 스킬 서버를 생성한다.
  - 챗봇 관리자센터에서 스킬을 생성하여 생성한 스킬 서버의 *엔드포인트를 등록한다.
- 스킬을 블록에 연결한다.
- 스킬과 연결한 블록이 활성화되면(ex. 사용자가 블록에 등록된 발화로 봇에게 말을 건 경우), 봇 시스템은 스킬에 등록된 엔드포인트로 요청을 전송한다.
- 스킬 서버에서 응답을 만들어 반환하면, 봇 시스템은 이를 토대로 사용자에게 전달할 출력 모습을 만들고 카카오톡에 그린다.
공식 문서에서의 스킬 설명: “ 발화에 따라서 출력의 큰 틀이 바뀌거나 많은 요소들이 바뀌는 상황이라면 일일이 데이터로 바꾸는 것보다 통째로 응답을 만들어서 주는 것이 낫습니다. 그리고 대화의 흐름을 조금 더 유연하게 제공해야 하는 상황에서도 출력으로써의 스킬은 빛을 발합니다.”

파라미터(Parameter) 설정

봇이 사용자의 의도를 정확히 이해하기 위해 필요로 하는 데이터를 말한다.
API 형태로 구성된 스킬(Skil)은 데이터가 입력되면, 들어온 데이터에 맞는 다양한 결과값을 보내준다. 이때, 스킬에 보내지는 데이터 또한 파라미터이다.

파라미터 구성 요소
- 파라미터 명
- 엔티티
- 값:
- 엔티티 값
  - $로 시작하는 이름으로 구성된 값.
  - 주로 파라미터 이름과 동일하게 사용.
  - ex) $paramName1, $paramName2, …

특정 값
- 값 위치에 ‘#’으로 시작하는 이름으로 구성된 값
- ‘current’를 사용해서 접근할 수 있는 값은 현재 대화의 발화 내용
- ‘request payload’의 특정 path 값
- ex) #[current|contextName].[path].[to]

고정된 값
- ‘$’ 이나 ‘#’ 으로 시작하지 않는 값.
- 값 체가 실제 파라미터의 값으로 사용

기본값
- 필수 파라미터로 지정되지 않고 사용자의 발화나 이전 또는 현재의 특정 값을 참조하거나, 고정된 값이 설정되어 있지 않을 경우에 ‘기본 값’으로 채택해 사용되는 기본적인 값입니다.

파라미터에 연결된 스킬 실행 과정

연결된 스킬의 실행은 모두 ‘HTTP request’로 이루어집니다.
HTTP method 중 ‘POST’만을 지원하고 있으며, ‘request/response’값에 모두 JSON형태를 사용하고 있습니다. ‘Request payload’는 동작에서 정의한 파라미터들의 구성에 따라서 ‘JSON’의 구성이 달라집니다.
동작에서 구성한 파라미터 이외의 값들로는 사용자의 대화 request 안에 들어 있는 “user”, “params” 라는 예약된 필드의 값들이 그대로 전달됩니다. 그리고, 현재까지 누적되어 있는 컨텍스트의 목록 또한 “contexts” 라는 이름으로 전달 됩니다.
이외에 http header 에는 “X-Request-Id” 라는 형태로 하나의 대화에 부여된 유일한 값인 footprint id 값을 같이 전달하게 됩니다.
Skill Request body

{
  "userRequest": [REQUEST OBJECT],
  "bot": {
    "id": "bot id",
    "name": "bot name"
  },
  "action": {
    "id": "action id (uuid)",
    "name": "builder에서 등록한 이름",
    "params": {
      "param name" : "resolved value"
      ....
    }
    "detailParams": {
      "param name" : {
        "origin": "origin value in utterance",
        "resolved": "resolvedValue from NLU engine"
      },
      ...
    }
  }
}

Request payload 구조

{
    "isInSlotFilling": true or false
    "utterance": "current request's utterance",
    "value": {
        "origin": "orignal value",
        "resolved": "resolved value(by AIU or etc.)"
    },
    "user": {
        // vsc 에서 전달된 data 그대로 전달
        "id": "id of user",
        "type": "type of id"
    }
}

예약된 Response JSON 구조

{
    "status": "SUCCESS|FAIL|ERROR|IGNORE", // 현재는 SUCCESS 만 다룸.(SUCCESS - 성공, FAIL - 실패,
    ERROR - API 실행중 ERROR 발생, IGNORE - 그냥 이 결과를 무시)
    "value": "Action 에 의해서 해석된 value",
    "data": {
        // something to pass to client(API 가 Action 으로 전달하고자 하는 데이터를 담는 곳, 아직 구현되지 않음)
    },
    "message": "..." // String type
}

컨텍스트 (Context)

사람과 봇 사이에서도 대화를 나눌 때 컨텍스트를 사용하여 문맥적 상황 공유를 할수 있다.
서로 다른 블록 간 ‘연결고리’를 만들고 싶을 때 사용한다. 이 연결고리가 곧 컨텍스트이다. 서로 다른 의도를 나타내는 블록들이 하나의 컨텍스트로 묶여서 연결될 수 있다.

전달 가능: 현재 블록의 파라미터 정보
전달 불가: 현재 블록을 실행시킨 사용자의 발화정보
- 단, 사용자의 발화정보는 스킬서버에서 처리하면 기능 구현이 가능하다. '스킬서버'에서 응답을 줄 때 유저의 발화정보를 넣어주면 전달할 수 있다.
예시

설정 방법, 구성 요소
- 컨텍스트 메뉴의 3가지 필요 구성값
  - 인풋(Input) 컨텍스트
  - 아웃풋(Output) 컨텍스트
    - 컨텍스트 명칭
    - 컨텍스트 수명
      - 컨텍스트가 지속되는 블록 횟수
      - 0/1/3/5/10 (회)
    - 유효시간
      - 컨텍스트가 지속되는 시간
      - 1/3/5/10/15/30/60 (분)
  - 대화 문맥이 살아있는 '컨텍스트 수명(Lifespan)'과 '유효시간(TTL)'

봇 테스트

챗봇 관리자센터에서 봇 작업자가 봇을 만들때 실제 카카오톡 채널이 아닌 웹 상에서 봇을 테스트할 수 있다.
블록의 응답 설정 값을 확인할 수 있다.

① 블록명 : 해당 발화/ 응답이 진행된 블록의 이름이 표기됩니다
② 패턴 : 해당 발화를 인지했다면, 인식된 패턴이 표기됩니다.
③ 컨텍스트 : 현재 발화로 인해 소비된 컨텍스트의 수명(lifespan) 횟수가 표기됩니다.
④ 파라미터 : 해당 발화의 파라미터 정보가 표기됩니다.
⑤ 스킬명 : 스킬로 연결된 블록인 경우, 연결된 스킬명이 노출됩니다.
⑥ 응답 사이즈 : 설정된 응답의 사이즈 정보가 표기됩니다. 텍스트형 및 이미지형 응답의 경우, 응답 사이즈를 제공하지 않습니다.
더보기 메뉴
- 스킬응답 : 스킬응답에 대한 JSON 전문이 표기됩니다.
- 응답오류 : 응답 오류가 된 경우, 오류관련 코드가 표기됩니다.
- Request : 스킬서버로의 요청 전문이 표기됩니다.

개발 이슈

스킬 응답 5초 타임아웃
- 문제
  - 스킬 서버의 응답 제한 시간은 기본적으로 5초이다. 이는 사용자가 임의로 수정할 수 없는 값이다.
  - 챗샘 챗봇 개발 도중, Chat GPT 응답 생성에 5초 이상이 소요되어, 정상적으로 챗봇 스킬 응답을 할 수 없는 문제가 발생하였다.
- 해결 방안
  - AI 챗봇 신청, 콜백 사용 https://cs.kakao.com/helps?articleId=1073206022&service=169&category=583&device=2153&locale=ko
  - “스킬의 처리시간이 오래 걸려 카카오 챗봇 플랫폼의 SLA(skill timeout: 5sec)를 준수하지 못하는 경우를 위하여 블록 단위로 콜백 옵션을 설정할 수 있는 기능을 제공하고 있습니다. 콜백URL은 해당 스킬 처리 후 응답을 전달하기 위한 목적으로만 사용되어야 하며, 일정시간(callbackUrl valid time: 1min)동안 유효하며 1회에 한하여 사용할 수 있습니다.”
  - 콜백 사용을 위해서는 이메일로 ‘AI 챗봇’ 신청을 해야 한다.
  - https://kakaobusiness.gitbook.io/main/tool/chatbot/skill_guide/ai_chatbot_callback_guide
- 관련 이슈
  - https://devtalk.kakao.com/t/topic/128246/7
블록 작동 원리
- 사용자 발화를 기반으로, 화자의 의도에 해당하는 블록이 추출되고 출력으로 이어져 실행되는 모습

'외부 API' 카테고리의 다른 글

[Kakao 챗봇] 4. 챗봇 구현 일지 (0)	2025.09.03
[Kakao 챗봇] 3. 스킬 개발 (0)	2025.09.03
[Kakao 챗봇] 2. 챗봇 관리 (0)	2025.09.03
Upstage AI (0)	2025.09.03

현재글[Kakao 챗봇] 1. 주요 개념, 메모

뭐라도보여드리겠습니다

메모장 상위호환

웹-csv-전처리, 카카오 챗봇 스킬서버, Docker killed error, 카카오 API, FE-csv처리, 인증서맵, error, 스킬서버 구성, danfo-js, kakao 챗봇, 개발 과정, 카카오 developers, 스킬서버, javascript, disutil, nvidia docker, shallow-routing, react-csv, nextjs, python error, 인증서 관리자, 부하 분산기, async await, docker, 카카오 챗봇, python, DB 포트포워딩, 기록, ai 스킬서버, KaKao Developers,

Today :
Yesterday :

뭐라도보여드리겠습니다

[Kakao 챗봇] 1. 주요 개념, 메모

참고

주요 개념

요약

상세

사용자 발화 (Utterance)

엔티티(Entity)

블록(Block)

시나리오(Scenario)

발화 패턴

스킬(Skill)

파라미터(Parameter) 설정

컨텍스트 (Context)

봇 테스트

개발 이슈

'외부 API' 카테고리의 다른 글

'외부 API'의 다른글

티스토리툴바

« 2026/03 »
일	월	화	수	목	금	토
1	2	3	4	5	6	7
8	9	10	11	12	13	14
15	16	17	18	19	20	21
22	23	24	25	26	27	28
29	30	31

[Kakao 챗봇] 1. 주요 개념, 메모

참고

주요 개념

요약

상세

사용자 발화 (Utterance)

엔티티(Entity)

개발 이슈

'외부 API' 카테고리의 다른 글

'외부 API'의 다른글

관련글

티스토리툴바