[Kakao 챗봇] 3. 스킬 개발

스킬 개발

• https://kakaobusiness.gitbook.io/main/tool/chatbot/skill_guide

스킬 개발 가이드 | kakao business 비즈니스 가이드

 

1. 스킬 서버 세팅

스킬을 사용하기 위해서, 먼저 스킬 서버를 세팅해야 한다.

일반적인 API 서버를 만드는 것과 방식이 동일하나, 다음 규칙을 지켜야한다.

• 봇 시스템의 요청은 스킬서버로 HTTP POST를 통해서 전달된다.
• 요청과 응답 모두 JSON으로 구성된 body를 이용한다.
• payload, response body 규격을 지켜야한다.
• 응답 타임아웃은 5초이다.
• localhost는 스킬 서버로 사용이 불가능하다.

'AI 챗봇 콜백'을 위한 API 개발

• ‘AI 챗봇’은 생성형AI 모델을 기반으로 답변을 생산하는 챗봇이다. AI 챗봇으로 전환하면 ‘콜백 관련 스킬’을 사용할 수 있다.
• AI 챗봇 전환을 위해, ‘AI 챗봇 신청’이 필요하다. ‘챗봇 관리자 센터 > 챗봇 선택 > 설정 > AI 챗봇 관리’에서 신청할 수 있다.
• 생성형 AI(Chat GPT 등)를 챗봇 응답에 사용하기 위해서는 ‘AI 챗봇’ 전환이 필수적이다. 이는 콜백 옵션을 설정할 경우 카카오 챗봇 플랫폼의 스킬의 처리시간 SLA(skill timeout: 5sec) 초과될 때에도 응답을 받아올 수 있기 때문이다.
• 콜백URL은 해당 스킬 처리 후 응답을 전달하기 위한 목적으로만 사용되어야 하며, 일정시간(callbackUrl valid time: 1min)동안 유효하며, 1회에 한하여 사용할 수 있다.
• 봇테스트에서 콜백 기능을 완전히 지원하지 않으므로 봇배포를 수행하면서 테스트 해야한다.
• Skil 서버 API 규격

• Skill Payload 규격 (봇 시스템 → 스킬 서버)

{
    "bot": ...,
    "intent": ...,
    "action": ...,
    "userRequest": {
        "callbackUrl": "<callback 호출시 사용할 url>",
        "block": {
            "id": "<블록 id>",
            "name": "<블록 이름>"
        },
        "user": {
            "id": "<사용자 botUserKey>",
            "type": "botUserKey",
            "properties": {
                "botUserKey": "<사용자 botUserKey>",
            }
        },
        "utterance": "<사용자 발화>",
        "params": {
            "surface": "BuilderBotTest",
            "ignoreMe": "true"
        },
        "lang": "kr",
        "timezone": "Asia/Seoul"
    },
    "contexts": ...
}

• Skill Response 규격 (스킬 서버 → 봇 시스템)

{
  "version" : "2.0",
  "useCallback" : true,
  "context": {
    ...
  },
  "data": {
    ...
  }
}

 

일반 스킬 서버 API 규격

응답 타입별 JSON 포맷 | kakao business 비즈니스 가이드

응답 타입별 JSON 포맷 | kakao business 비즈니스 가이드

• payload 규격 (봇 시스템 → 스킬 서버)

형식

{
   "intent": { … },
   "userRequest": { … },
   "bot": { … },
   "action": { … },
   "flow": { … },
}

 

예시

{
    "bot": {
        "id": "<봇 id>",
        "name": "<봇 이름>"
    },
    "intent": {
        "id": "<블록 id>",
        "name": "지식+",
        "extra": {
            "reason": {
                "code": 1,
                "message": "OK"
            },
            "knowledge": {
                "responseType": "skill",
                "matchedKnowledges": [
                    {
                        "categories": [
                            "<카테고리 1>",
                            "<카테고리 2>",
                            "<카테고리 3>",
                            "<카테고리 4>"
                        ],
                        "question": "<질문>",
                        "answer": "<답변>",
                        "imageUrl": "<이미지 url>",
                        "landingUrl": "<랜딩 url>"
                    },
                    {
                        "categories": [
                            "<카테고리 1>",
                            "<카테고리 2>",
                            "<카테고리 3>",
                            "<카테고리 4>"
                        ],
                        "question": "<질문>",
                        "answer": "<답변>",
                        "imageUrl": "<이미지 url>",
                        "landingUrl": "<랜딩 url>"
                    }
                ]
            }
        }
    },
    "action": {
        "id": "<액션 id>",
        "name": "<액션 이름>",
        "params": {},
        "detailParams": {},
        "clientExtra": {}
    },
    "userRequest": {
        "block": {
            "id": "<블록 id>",
            "name": "<블록 이름>"
        },
        "user": {
            "id": "<사용자 botUserKey>",
            "type": "botUserKey",
            "properties": {
                "botUserKey": "<사용자 botUserKey>"
            }
        },
        "utterance": "<사용자 발화>",
        "params": {
            "surface": "BuilderBotTest",
            "ignoreMe": "true"
        },
        "lang": "ko",
        "timezone": "Asia/Seoul"
    },
    "contexts": []
}

• response 규격 (스킬 서버 → 봇 시스템)
• 응답 타입에 따라서 응답 규격이 다르다. 자세한 내용은 공식 가이드 문서를 참고한다.
• 응답 타입별 JSON 포맷 | kakao business 비즈니스 가이드

형식

{
   version: "...",
   template: { … }
}​

 

예시

{
  version: "2.0",
  template: {
      outputs: [
       {
         simpleText: {
           text: "hello I'm Ryan"
         }
       }
     ]
  }
}

 

 

2. 스킬 등록

• ‘스킬 > 스킬 목록’에서 ‘생성’ 버튼을 클릭한다.
• 스킬 서버의 API 엔드포인트, 헤더값 등을 입력 후 저장한다.

 

3. 블록에 스킬 적용

블록에 스킬 적용하기 | kakao business 비즈니스 가이드

• 2번에서 만든 스킬을 블록에 연결한다.
• 스킬과 연결한 블록이 활성화되면(ex. 사용자가 블록에 등록된 발화로 봇에게 말을 건 경우), 봇 시스템은 스킬에 등록된 엔드포인트로 요청을 전송한다.

봇 응답 형식 설정

• 스킬 결과를 응답 형식에서 이용하는 방법은 다음 두 가지가 있다.

.1. 응답설정을 값으로 사용하기

• 웹훅 객체(webhook)를 사용하여 봇 응답 말풍선을 구성하는 방법이다.
• 스킬 서버에서 응답하는 값을 {{#webhook.<json_path>}}과 같은 형태로 사용한다.\
• 스킬 서버 응답 값

{
 "version": "2.0",
 "data": {
   "name": "홍길동"
 }
}

• 응답형식(말풍선) 선택 및 값 입력

 

2. 응답설정을 스킬로 사용하기

• 스킬에서 직접 말풍선을 구성해서 응답하는 방법이다.