AI 챗봇 콜백 개발 가이드
개요
AI 챗봇은 생성형AI 모델을 기반으로 답변을 생산하는 챗봇입니다.
AI 챗봇으로 전환하면 개발에 필수적인 콜백 관련 스킬을 사용할 수 있습니다.
콜백 옵션을 설정할 경우 카카오 챗봇 플랫폼의 스킬의 처리시간 SLA(skill timeout: 5sec) 초과될 때에도 응답을 받아올 수 있습니다.
콜백URL은 해당 스킬 처리 후 응답을 전달하기 위한 목적으로만 사용되어야 하며 일정시간(callbackUrl valid time: 1min)동안 유효하며 1회에 한하여 사용할 수 있습니다.
Callback API 설정하기
콜백 기능은 봇 마스터만 신청 가능 하며 "챗봇 > 설정 > AI 챗봇 관리"에서 목적과 사유를 기입하여 신청할 수 있습니다.
가이드에 적합한지 검토 후 전환하여 드리고 있으며 승인은 영업일 기준 1~2일 정도 소요됩니다.
반려될 경우 사유를 확인하여 재신청이 가능하며, OFF 전환도 가능합니다.
AI 챗봇 전환은 스킬 쿼터 제한 등이 발생하기 때문에 자세한 내용은 챗봇 관리자센터 공지를 확인해 주십시오.
블록에 콜백 설정
Callback API 사용 권한을 부여받은 챗봇은 블록 상세에서 Callback API 설정 기능이 나타납니다.
해당 블록의 콜백 설정 활성화
콜백 설정 화면에서 활성화를 한 후 기본응답메시지를 작성합니다.
스킬을 연결, 스킬 응답데이터 사용
스킬 요청을 받을 스킬을 연결하고, 응답에서는 스킬데이터를 사용하도록 설정한다.
SkillPayload
특정 블록에 대해 콜백 옵션을 활성화하면 봇 엔진에서는 스킬 요청시 1회성 콜백URL을 발행하여 이를 요청(userRequest 부분)에 포함하여 스킬서버에 전달합니다. 기본적인 페이로드 구조는 동일하므로, 아래 개발 가이드를 참조 바랍니다.
userRequest 상세 필드
| 필드명 | 타입 | 설명 |
|---|---|---|
| callbackUrl | string | 콜백 요청을 전송할 URL입니다. |
| timezone | string | 사용자의 시간대를 반환합니다.한국에서 보낸 요청이라면 “Asia/Seoul”를 갖습니다. |
| block | Block |
|
| utterance | string | 봇 시스템에 전달된 사용자의 발화입니다. |
| lang | string |
|
| user | User | 사용자의 정보입니다. |
{
"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": ...
}
SkillResponse
Callback 응답을 완료하기 위해선 응답 페이로드에 useCallback을 true로 명시해서 반환해야 합니다.
(template 필드는 입력하지 않습니다.)
SkillResponse 상세필드
| 이름 | 타입 | 설명 |
|---|---|---|
| version | string | 응답포맷버전 2.0으로 설정 |
| useCallback | boolean | 콜백을 사용할 경우 true로 세팅해서 반환 |
| template | SkillTemplate | 무시 |
| context | ContextControl | 컨텍스트 정보 |
| data | Map<String, Any> | 데이터 설정 |
{
"version" : "2.0",
"useCallback" : true,
"context": {
...
},
"data": {
...
}
}
ture를 반환하는 부분으로 template 필드는 사용하지 않으나 만약 data를 사용할 경우 아래와 같이 Callback 대기 부분에 문구를 삽입하여 응용할 수 있습니다.
삽입은 응답 설정을 값으로 입력하는 부분을 참고하여 webhook 형태로 사용하여 주시기 바랍니다.
활용 예
{
"version" : "2.0",
"useCallback" : true,
"data": {
"text" : "생각하고 있는 중이에요😘 \n15초 정도 소요될 거 같아요 기다려 주실래요?!"
}
}
CallbackRequest
응답이 콜백으로 동작하기 위해서 Skill 페이로드로 전송된 callback_url로 원하는 응답을 HTTP 프로토콜로 POST 방식으로(JSON 코드) 요청하여 주시기 바랍니다.
요청 포맷은 스킬 응답 포맷과 동일하며, 사용자에게 최종 말풍선으로 응답됩니다.
CallbackResponse
콜백 응답이 성공적으로 전송되면 아래와 같은 형태의 콜백 전송 응답이 반환됩니다.
| 이름 | 타입 | 설명 |
|---|---|---|
| taskId | string | 해당 리퀘스트에 대한 uuid |
| status | string | 상태메시지 ["SUCCESS", "FAIL", "ERROR"] 중 하나 |
| message | string | 상태에 대한 세부 메시지 |
| timestamp | long | task 생성 unixtimestamp |
{
"taskId" : ...,
"status" : "SUCCESS",
"message" : ...,
"timestamp" : ...
}
제약사항
- 현재 봇테스트에서 콜백 테스트는 불가능합니다.
- 채널 관리자센터> 제네릭 메뉴 > 봇 유효발화 검증시 콜백이 연결되어 있는 블록의 경우, 해당 블록의 스킬 서버로 콜백 토큰이 발급되나 사용이 불가능합니다. 토큰 조회시 Invalid callback token for testing purposes라는 메시지가 노출됩니다.
주의사항
봇테스트에서 콜백 기능을 완전히 지원하지 않기 때문에 봇배포를 수행하면서 테스트해주시기 바랍니다.