스몰톡 API Reference

카카오 i 클라우드의 스몰톡 API를 호출할 때 필요한 개발 정보는 다음과 같습니다.

Request

Request Syntax

코드 예제 Request Syntax

curl -X POST "{API Endpoint URL}" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: {API Key}" \
  -d '{ ... }'

표 API 호출 방식

메서드	요청 URL
POST	요청 Body에 `application/json`으로 표현된 데이터

Request Header

표 Request Header

파라미터	타입	필수여부	설명
x-api-key	String	필수	`{API Key}`: API 호출 시 필요한 인증키 - 카카오 i 클라우드 콘솔 > Conversation > 도메인 탭의 [인증 정보] 버튼 클릭해 조회
Content-Type	String	필수	다음의 방식을 지원 - `application/json`

Request Elements

POST 요청 시, Request Elements는 다음의 구조를 갖는 JSON 객체로 표현됩니다.

표 Request Elements

파라미터	타입	필수여부	설명
userRequest ▼	Object	필수	사용자의 발화 및 사용자 정보를 담고 있는 필드
context	List[string]	선택	시간 상 이전의 발화 목록 - 스몰톡 Fallback API 호출이 이루어지지 않은 이전 턴의 대화 내용 - 최대 15개의 발화 입력 가능 - 발화 배열은 시간 순으로 유저와 봇의 발화를 교차 구성 - ex. [“사용자 발화 1”, “봇 답변 1”, “사용자 발화 2”, “봇 답변 2”] - 맥락 정보로 활용해 답변 품질 개선
utterance	String	필수	사용자 입력 발화 - 최소 1자, 최대 300자 허용
action ▼	Object	선택	실행되는 스킬의 정보를 담고 있는 필드로, 발화로부터 추출한 엔티티의 값을 추가로 포함
params	Object	선택	페르소나와 tone 타입 등 파라미터 값을 담기 위한 Map 객체 - 사용자의 발화로부터 추출한 파라미터 정보와 추가적인 정보로 구성 - body.action.params 최대 길이 제한은 2,500자 (`\|` 구분자 포함) - `\|` 로 구분 되는 각 항목의 길이 제한은 300자 - 자세한 설명은 Overview 문서 참고
tone	String	선택	스몰톡 Fallback API의 모든 답변에 적용되는 말투 - assistant(기본): 해요체의 가벼운 존댓말 - polite: 격식 있는 존댓말 - friendly: 반말
call_name_template	String	선택	챗봇 사용자가 으로 챗봇 호출 시 봇의 답변 - 자세한 설명은 [Overview > 호출 답변 설정](/docs/posts/aiservice-conversation/smalltalk/2022-07-28-aiservice-smalltalk_overview/aiservice-smalltalk_overview#%ED%98%B8%EC%B6%9C-%EB%8B%B5%EB%B3%80-%EC%84%A4%EC%A0%95){:target="_blank"} 참고
you_directive	String	선택	챗봇이 사용자를 부르는 호칭 - 자세한 설명은 Overview > 호칭 설정 참고
fallback	String	선택	하드 폴백 답변 - 칭찬, 인사, 감사, 축하, 비난 등을 제외한 질의나 평서문에 사용할 특정 답변 - 자세한 설명은 Overview > 답변 범위 설정 참고
{페르소나 항목}	String	선택	이름, 성별, 나이 등 개성 있는 답변을 위한 페르소나 설정 - 최소 1글자, 최대 300 글자 (빈 문자열 허용 X) - 자세한 설명은 Overview > 페르소나 설정 참고
{페르소나 항목}_template	String	선택	커스텀 페르소나 답변 설정 - 최소 1글자, 최대 300 글자 (빈 문자열 허용 X) - 자세한 설명은 Overview > 커스텀 페르소나 답변 설정 참고

주의
{페르소나 항목}_template에 필요한 {페르소나 항목} 값이 없는 경우, 422 Validation Error가 발생합니다.

코드 예제 스몰톡 API 요청 Syntax

{
  "userRequest": {
    "context" : [
      "<맥락 발화1>",
      "<맥락 발화2>",
      ...
    ],
    "utterance": "<User 입력 발화>",
    "user": {
      "id": "<User id>",
      "type": "<User id 타입>" 
    }
  }, 
  "bot":{
    "id": "<Bot id>",
    "name": "<Bot 이름>" 
  },
  "action":{ 
    "params":{
      "tone": "<tone 타입>", 
      "name": "<페르소나 이름>", 
      "age": "<페르소나 나이>",
      ...
    } 
  }
}

Response

Response Body는 다음의 구조를 갖는 JSON 객체로 표현됩니다.

Response Syntax

코드 예제 Response Syntax

{
  "input": {
    "utterance": "<User 입력 발화>",
    "context": {
      "fromDB": false,
      "turns": [
        "<맥락 발화1>",
        "<맥락 발화2>",
        ...
      ]
    },
   
  "output": {  
    "response": "<최종 답변 문장 텍스트>",
    "type": "<답변 유형 코드>",
    "tone": "<답변 톤 타입>"
  },
  "release": "1.10.0"
}

Response Elements

표 Response Elements

필드	타입	필수여부	설명
input ▼	Object	필수	사용자 입력 관련 필드
utterance	String	필수	사용자 입력 발화
context ▼	Object	필수	사용자 입력 이전의 챗봇과 사용자 간의 턴으로 구성된 대화 - 맥락 정보로 활용
fromDB	Boolean	필수	입력한 맥락 정보가 없을 경우 스몰톡 API가 자체적으로 관리한 맥락을 표현 - true: Request Elements에 context 정보가 명시된 경우 - false: 그 외의 경우 또는 스몰톡 API가 자체적으로 DB에 저장된 맥락을 이용한 경우
turns	String[]	필수	문자열의 배열로, 시간 순에 따라 사용자 입력 이전의 대화 내용 - 입력 파라미터(발화 15개)와 달리 내부 처리에 사용한 최신 발화 6개 출력 - 향후 모델 개선에 따라 출력 발화수 증가 예정
output ▼	Object	필수	봇의 답변 관련 필드
response	String	필수	봇의 최종 출력 문장 - output.origin 필드의 값에 “/n/”가 있을 경우 “\n”로 치환하여 표현
type	String	필수	봇의 답변 유형 코드 - PROFILE-{대문자}: 페르소나 관련 답변 - FALLBACK: fallback 파라미터에 의한 답변 - FILTER: 이슈 발화로 탐지되어 필터링된 답변 - TEMPLATE: 내부 단순 템플렛 기반 답변 (페르소나 템플릿과 별개) - SEARCH: 사전 구축된 데이터에서 검색되어 나온 답변 - REACTION: 리액션 딥러닝 모델에 의한 답변 - URL, IMAGE-URL, FAKE-URL: 사용자 발화가 URL만 포함된 경우 나오는 답변 - EMOJI-ONLY: 사용자 발화에 emoji 만 입력된 경우 나오는 답변
tone	String	필수	설정한 답변 말투
release	String	필수	스몰톡 API 모델 버전

Status Code

표 Status Code

응답 코드	응답 내용	설명
200	-	API 호출 성공
206	-	API 호출 성공했으나, 일부 기능이 호출 옵션과 달리 작동한 경우 - 일시적인 예외 처리가 발생한 경우
400	Bad Request	요청 주소가 잘못된 경우 - Payload가 유효하지 않거나, 유효하지 않은 JSON 문법 등의 잘못된 요청
	INVALID_SIGNATURE	요청 Endpoint 주소의 signature가 잘못된 경우
	INPUT_CONTEXT_OVERFLOW	context 값의 길이가 최대 발화 수(6 발화)를 초과한 경우
401	Authentication failed	x-api-key 헤더가 없거나 값이 잘못된 경우
404	NOT FOUND	지원하지 않는 Method로 요청을 보낸 경우
405	Method Not Allowed	지원하지 않는 Method로 요청을 보낸 경우
413	Request Entity Too Large	요청의 크기가 제한보다 큰 경우
415	Unsupported content type	Content Type 헤더가 없거나 규격에 맞지 않는 경우
422	INVALID_PARAMETER_TYPE	파라미터 타입 오류
	INVALID_PARAMETER_VALUE	파라미터 값 오류 - ex. 길이 제한 초과, 지원되지 않는 값 등
425	Domain not found	요청한 도메인이 삭제되어 없을 경우
	Domain not deployed	요청한 도메인이 아직 배포되지 않은 경우
429	Too many Requests	설정한 한도를 초과해서 요청한 경우
503	INTERNAL ERROR	예상하지 못한 서버 오류가 발생한 경우

안내
제시된 스몰톡 API 성능보다 더 높은 성능이 필요한 경우에는 헬프데스크 > 기술문의 또는 상담 및 도입 문의으로 문의하시기 바랍니다.

클라우드 가이드 센터 User Guide

스몰톡 API 호출 가이드

페이지 이동경로

스몰톡 API Reference

Request

Request Syntax

Request Header

Request Elements

Response

Response Syntax

Response Elements

Status Code