2.kakao biz 상담톡 API

Edit

2.1개요

2.2용어 정의

2.2.1허브 파트너(Hub Partner)

2.2.2카카오톡 채널(Kakao Talk Channel)

2.2.3상담 세션(Session)

2.2.4사용자 키 (User Key)

2.2.5상담원의 정의

2.2.6상담 메시지

2.3선결 조건

메시지 API를 사용하여 메시지 전송을 대행하기 위해 아래의 조건이 선결되어야 한다.

2.4API 스펙

2.4.1[서버] sip 서버

2.4.2메시지 발신

[Request]
POST /chat/write
[Parameter]

키

타입

필수

설명

user_key

text(20)

Y

사용자 키

sender_key

text(40)

Y

발신 프로필 키

message_type

text(2)

N

메시지 타입

(TX : 텍스트, IM : 이미지, FI: 일반파일,

AU: 오디오파일, LI : 링크타입, BS:봇정보)

버튼 (기본값은 TX))

message

text(1000)

Y/N

사용자에게 전달할 메시지

message_type이 TX, LI인 경우 필수

image_url

text(1000)

Y/N

사용자에게 전달될 이미지 url

message_type이 image인 경우 필수

file_url

text(1000)

Y/N

사용자에게 전달될 파일 url

message_type이 일반파일, 오디오

파일인 경우 필수

file_name

text(1000)

Y/N

사용자에게 전달될 파일이름

message_type이 일반파일인 경우필수

file_size

text(1000)

Y/N

사용자에게 전달될 파일용량

message_type이 일반파일인 경우필수

auto_answer

text(2)

Y/N

시스템 자동 응답 메시지

상담불가 : 'S1'

상담부재 : 'S2'

무응답 상담종료 : 'S3'

links

json

N

링크타입(멀티버튼)

bot_id

text(128)

N

넥서스 시나리오 봇 아이디(콜아이디)

bot_name

text(100)

N

넥서스 시나리오 봇 이름

bot_status

text(10)

N

START: 시작 메시지, ING: 채팅중 , CLOSE:종료,

TIMEOUT: 고객 응답 없음, CONNECT: 상담원 연결, BUSY:대기 상담원 없음.

EXPIRE: 고객상담종료

[Parameter] - links

키

-

타입

필수

설명

links

-

array

-

버튼 목록


name

text(28)

Y

버튼명


type

text(2)

Y

버튼 타입 <4.2.1 버튼 타입에서 확인 가능>


scheme_android

text

-

mobile android 환경에서 버튼 클릭 시 실행할

application custom scheme


scheme_ios

text

-

mobile ios 환경에서 버튼 클릭 시 실행할

application custom scheme


url_mobile

text

-

mobile 환경에서 버튼 클릭 시 이동할 url


url_pc

text

-

pc 환경에서 버튼 클릭 시 이동할 url


extra

text(100)

N

BK, MD 버튼 발송 시 전달할 extra 정보


event

text(100)

N

상담톡에서 봇 상담으로 전환시 호출할 봇 이벤트명

[Response]

키

타입

필수

설명

code

integer

Y

처리 결과 코드

(0은 정상 / 나머지는 오류)

createdAt

datetime

N

메시지 발송 후 DB에 저장된 시각

("2018-01-31T15:27:24.514")

2.4.2.1버튼 타입별 속성

필수 파라메터를 모두 입력하셔야 정상적인 발송이 가능합니다.

표 2-1button 타입별 속성

버튼타입

속성

타입

필수

설명

WL

url_mobile

text

Y

버튼 클릭 시 이동할 pc/mobile환경별 web url


url_pc

text

N


AL

scheme_android

text

-

scheme_ios, scheme_android, url_mobile 중 2가지 필수 입력

mobile android 환경에서 버튼 클릭 시 실행할

application custom scheme


scheme_ios

text

-

mobile ios 환경에서 버튼 클릭 시 실행할

application custom scheme


url_mobile

text

-

mobile 환경에서 버튼 클릭 시 이동할 url


url_pc

text

N

pc 환경에서 버튼 클릭 시 이동할 url

BK

-

-

-

해당 버튼 텍스트 전송

MD

-

-

-

해당 버튼 텍스트 + 메시지 본문 전송

BT

event

text(100)

N

상담톡에서 봇상담으로 전환 (상담톡 세션 종료)

  • 상담톡 세션 종료하고, 봇 이벤트 호출

  • 모바일에서만 동작

  • PC톡/맥톡에서는 말풍선 전송되나 버튼은 동작하지 않음(추후 추가 예정)

[Response]

키

타입

필수

설명

code

integer

Y

처리 결과 코드

(0은 정상 / 나머지는 오류)

message

text

N

오류 메시지

(오류시 존재하는 값)

2.4.2.2상담톡 발신 메시지 타입

2.4.2.2.1텍스트 타입

2.4.2.2.2이미지 타입

2.4.2.2.2.1이미지 업로드
[Request]
POST /image/upload
[Header]

Content-type: multipart/form-data

[Parameter]

키

타입

필수

설명

sender_key

text

Y

발신프로필 키

image

binary

Y

업로드할 이미지 파일

image_type

text

N

링크버튼 전용 이미지(link). link 버

튼 사용시 필수

("image_type=link")

[Response]

키

타입

필수

설명

code

integer

Y

처리 결과 코드

(0은 정상 / 나머지는 오류)

image

text

N

업로드된 이미지 경로

("image":"http://mud-kage.kakao.com/original.jpg")

2.4.2.2.2.2파일 업로드
[Request]
POST /file/upload
[Header]

Content-type: multipart/form-data

[Parameter]

키

타입

필수

설명

sender_key

text

Y

발신프로필 키

file

binary

Y

업로드할 파일

file_type

text

N

file 일반파일 (기본값), audio 오디

오 파일

("image_type=audio")

[Response] 일반파일

키

타입

필수

설명

code

integer

Y

처리 결과 코드

(0은 정상 / 나머지는 오류)

file

text

N

업로드된 이미지 경로

("image":"http://mud-kage.kakao.com/original.jpg")

name

text

N

업로드된 파일 이름

size

text

N

업로드된 파일 용량

[Response] 오디오파일

키

타입

필수

설명

code

integer

Y

처리 결과 코드

(0은 정상 / 나머지는 오류)

file

text

N

업로드된 이미지 경로

("image":"http://mud-kage.kakao.com/original.m4a")

2.4.3사용자 차단

[Request]
POST /profile/user/block
[Parameter]

키

타입

필수

설명

user_key

text(20)

Y

사용자 키

sender_key

text(40)

Y

발신 프로필 키

[Response]

키

타입

필수

설명

code

integer

Y

처리 결과 코드

(0은 정상 / 나머지는 오류)

message

text

N

오류 메시지

(오류시 존재하는 값)

2.4.4사용자 차단 해제

[Request]
POST /profile/user/unblock
[Parameter]

키

타입

필수

설명

user_key

text(20)

Y

사용자 키

sender_key

text(40)

Y

발신 프로필 키

[Response]

키

타입

필수

설명

code

integer

Y

처리 결과 코드

(0은 정상 / 나머지는 오류)

2.4.5상담 종료

2.4.5.1일반적인 상담 종료

[Request]
POST /chat/end
[Parameter]

키

타입

필수

설명

user_key

text(20)

Y

사용자 키

sender_key

text(40)

Y

발신 프로필 키

[Response]

키

타입

필수

설명

code

integer

Y

처리 결과 코드

(0은 정상 / 나머지는 오류)

message

text

N

오류 메시지

(오류시 존재하는 값)

sessionId

text

N

종료된 세션아이디

(현재 요청에 의해 정상적으로 종료


된 세션이 있을 경우 존재하는 값)

2.4.5.2상담 종료 후 지정된 봇 이벤트 말블럭을 실행 (봇이 설정된 경우만 가능)

[Request]
POST /chat/endWithBot
[Parameter]

키

타입

필수

설명

user_key

text(20)

Y

사용자 키

sender_key

text(40)

Y

발신 프로필 키

bot_event

text(100)

N

봇 이벤트 명

("bot_evnet":"hello")

[Response]

키

타입

필수

설명

code

integer

Y

처리 결과 코드

(0은 정상 / 나머지는 오류)

message

text

N

오류 메시지

(오류시 존재하는 값)

sessionId

text

N

종료된 세션아이디

(현재 요청에 의해 정상적으로 종료

된 세션이 있을 경우 존재하는 값)

2.4.6카카오톡 채널 1:1 채팅 내역 조회 기능

2.4.6.1카카오톡 채널 1:1 채팅 내역 조회 신청

[Request]
POST /agreement/request
[Parameter]

키

타입

필수

설명

sender_key

text(40)

Y

발신 프로필 키

[Response]

키

타입

필수

설명

code

integer

Y

처리 결과 코드

(0은 정상 / 나머지는 오류)

2.4.6.2카카오톡 채널 1:1 채팅 내역 조회

[Request]
POST /agreement/user/message
[Parameter]

키

타입

필수

설명

sender_key

text

Y

발신 프로필 키

user_key

text

Y

사용자 키

prev_id

long

N

이전 메시지 아이디(처음 호출시에

는 빈값)

[Response]

키

타입

필수

설명

code

integer

Y

처리 결과 코드

(0은 정상 / 나머지는 오류)

has_prev

boolean

Y

이전 메시지 존재 여부

prev_id

long

N

이전 메시지 아이디, has_prev가 true 일때 추가 내역이 필요한경우

요청시 prev_id에 값을 넣어 요청

messages

array

Y

이전 대화 내역 메시지 리스트

표 2-2messages 상세

키

타입

필수

설명

writer_type

text

Y

작성자

(U : 유저 P : 톡채널)

type

text

Y

메시지 종류

(text, photo, video, audio)

message

text

Y

메시지 내용

url

text

N

파일 url("url":null)

sent_at

text

Y

작성일 ("2019-10-23 17:03:35")

2.4.7카카오톡 사용자 정보

2.4.7.1카카오톡 사용자 정보 조회

[Request]
GET /user/info
[Parameter]

키

타입

필수

설명

sender_key

text(40)

Y

발신 프로필 키

user_key

text(20)

Y

사용자 키

[Response]

키

타입

필수

설명

code

text

Y

처리 결과 코드

(200은 정상 / 나머지는 오류)

message

text

N

처리 메시지

sender_key

text

N

발신 프로필 키

user_key

text

N

사용자 키

tel_number

text(20)

N

사용자 전화번호

user_name

text(100)

N

사용자 이름

user_id

text(100)

N

사용자 ID

agree_type

int

N

사용자 인증 구분

0: 지속인증(기본값), 1: 1회성 인증

agree_date

text

N

동의일자: "2019-10-23 17:03:35"

[Example]
http://127.0.0.1:8080/user/info?sender_key=da2b0c0d28805157d5355b60beb9493a9b3e5b15&user_key=d14zPgU4yqoO&
{
  "code": "200",
  "message": "OK",
  "user_key": "d14zPgU4yqoO",
  "sender_key": "da2b0c0d28805157d5355b60beb9493a9b3e5b150",
  "user_id": "",
  "user_name": "",
  "tel_number": "1112323",
  "agree_type": 0, 
  "agree_date": "2022-05-11 15:40:04"
}

2.4.7.2사용자 정보 인증

[Request]
POST /user/auth
[Parameter]

키

타입

필수

설명

sender_key

text

Y

발신 프로필 키

user_key

text

Y

사용자 키

tel_number

text(20)

Y

사용자 전화번호

user_name

text(100)

N

사용자 이름

user_id

text(100)

N

사용자 ID

agree_type

int

N

사용자 인증 구분

0: 지속인증(기본값), 1: 1회성 인증

[Response]

키

타입

필수

설명

code

text

Y

처리 결과 코드

(200은 정상 / 나머지는 오류)

message

text

N

응답 메시지

[Example]
curl -X POST -H "Content-type: application/json" \
  -d '{"user_key":"d74zPgU4yqoO","sender_key":"da2b0c0d28805157d5355b60beb9493a9b3e5b15","app_user_id":null,"user_name":"장형길","user_id":"kenneth","tel_number":"01029113333" }'  \
  http://127.0.0.1:8080/user/auth
{ 
    "code": "200", 
    "message": "OK" 
}

2.4.7.3사용자 정보 인증 철회

[Request]
post /user/auth/delete
[Parameter]

키

타입

필수

설명

sender_key

text

Y

발신 프로필 키

user_key

text

Y

사용자 키

[Response]

키

타입

필수

설명

code

text

Y

처리 결과 코드

(200은 정상 / 나머지는 오류)

message

text

N

응답 메시지

[Example]
curl -X POST -H "Content-type: application/json" \
  -d '{"user_key":"d74zPgU4yqoO","sender_key":"da2b0c0d28805157d5355b60beb9493a9b3e5b15" }'  \
  http://127.0.0.1:8080/user/auth/delete
{ 
    "code": "200", 
    "message": "OK" 
}

2.4.8카카오톡 사용자 세션정보

2.4.8.1카카오톡 사용자 세션 정보 조회

[Request]
GET /session/list
[Parameter]

키

타입

필수

설명

sender_key

text(40)

N

발신 프로필 키

agent_dn

text(32)

Y

상담원 DN 값

[Response]

키

타입

필수

설명

code

integer

Y

처리 결과 코드

(0은 정상 / 나머지는 오류)

message

text

N

결과 설명

sessions

array


세션 리스트

표 2-3sessions 상세

키

타입

필수

설명

session_id

text

Y

세션 ID

extra

text

Y

사용자 메타 데이터

uuid

text

Y

U PBX 에서 전달 받은 세션ID

agent_dn

text

Y

상담원 DN 값

agent_vdn

text

N

최초 상담원 VDN 값(참고만 하면 됨, 미사용)

reply

bool

N

상담원 답변여부 ( 고객 메시지가 마지막일 경우 false , 상담원 메시지가 마지막일 경우 true)

last_message

text

Y

마지막 메시지 정보 ( text 메시지 일 경우 최대 200 byte 만 표시됨)

[Example]
http://127.0.0.1:8080/session/list?sender_key=da2b0c0d28805157d5355b60beb9493a9b3e5b15&agent_dn=1004
{
  "code": "200",
  "message": "OK",
  "sessions": [
    {
      "session_id": "224002311",
     "extra": "category_id|1|division_id|8|",
     "uuid": "00FA08000100036555C976",
      "agent_dn": "30011",
      "agent_vdn": "30011"
    },
    {
      "session_id": "224508838",
     "extra": "category_id|1|division_id|8|",
     "uuid": "00FA0800010001655BFA3F",
      "agent_dn": "30011",
      "agent_vdn": "30011"
    }
    ]
}

2.4.8.2카카오톡 사용자 세션 정보 (PBX -> Biztalk)

[Request]
POST /session/info
[Parameter]

키

타입

필수

설명

sender_key

text(40)

Y

발신 프로필 키

user_key

text(20)

Y

사용자 키

uuid

text

Y

콜세션 UUID 값

agent_dn

text(32)

Y

상담원 DN 값

[Response]

키

타입

필수

설명

code

integer

Y

처리 결과 코드

(0은 정상 / 나머지는 오류)

message

text

N

결과 설명

[Example]
curl -X POST -H "Content-type: application/json" \
  -d '{"user_key":"d74zPgU4yqoO","sender_key":"da2b0c0d28805157d5355b60beb9493a9b3e5b15", "uuid":"00FA08000100036555C976", "agent_dn":"1004"  }'  \
  http://127.0.0.1:8080/session/info
{ 
    "code": "200", 
    "message": "OK" 
}

2.4.9넥서스 시나리오봇 연동

2.4.9.1넥서스 시나리오 봇 상태 저장

[Request]
POST /bot/status
[Parameter]

키

타입

필수

설명

sender_key

text(40)

Y

발신 프로필 키

user_key

text(20)

Y

사용자 키

status

text(20)

Y

상태값

Welcom : 시나리오봇 처음 나타남

Ing : 상담중

Completed : 상담완료

Exit: 고객 종료(상담완료 이전 종료)

bot_id

text(128)

Y

봇아이디 또는 call id

(동일한 고객의 상담일 경우 구별을 위한 키가 필요)

bot_name

text(100)

N

넥서스 시나리옷 봇 이름

[Response]

키

타입

필수

설명

code

text

Y

처리 결과 코드

(200은 정상 / 나머지는 오류)

message

text

N

처리 메시지

2.4.10메지시 첨부파일 가져오기

2.4.10.1첨부파일 가져오기

[Request]
GET /message/attachment
[Parameter]

키

타입

필수

설명

attachment_url

text(1024)

Y

첨부파일 URL

2.4.11첨부파일 가져오기

2.4.11.1첨부파일 가져오기

[Request]
GET /message/file
[Parameter]

키

타입

필수

설명

file_url

text(1024)

Y

첨부파일 URL

2.5카카오톡 연결

2.5.1버튼을 통한 상담 시작 (GET 방식)

[Parameter]

키

타입

필수

설명

예제

uuid

text

Y

카카오톡 채널 (@ 로 시작되는 아이디)

(해당 파라미터는 주소 맨 끝에 붙는다)

@tkaekaxhr

extra

text(50)

N

상담시 전달하고 싶은 메타 정보

메타정보에 추가정보를 위해서 앞에

prefix 를 붙여서 사용


* UUID 추가: _CID_번호

* DN 추가: _DN_번호

* MODE 추가 : _MODE_값

- INFO(기본값) : 상담원에게 정보 제공

- AGENT: 통화중 상담원에게 연결

extra=_UUID_1234890_DN_10004

=> 통화 정보 전달






extra=_UUID_15890_DN_10004_MODE_AGENT

=> 상담원에게 바로 연결

bot

text

N

"true"인 경우 봇으로 상담 시작

-bot:"false": 상담톡으로 시작(기본값)

-bot:"true": 봇으로 시작

-bot:"auto": 봇으로 시작하되, 상담 세션이 있을

경우 상담모드 유지(True 같이 대문자 불가)

event

text(50)

Y

봇으로 상담 시작 시 같이 실행될 봇

말블럭 이벤트명


2.5.2버튼을 통한 상담 시작

[Sample]
https://127.0.0.1/chat/open?yid={카카오채널명}&site_uid={site_uid}&site_id={site_id}

키

타입

필수

설명

예제

yid

text

Y

카카오톡 채널 (@ 로 시작되는 아이디)

(해당 파라미터는 주소 맨 끝에 붙는다)

yid=@tkaekaxhr

site_id

text

N

엡체 정보

site_id=_nexus

site_uid

text

N

고객 아이디 (고객정보 키)

site_uid=test111

category_id

text

N

상담 카테고리


division_id

text

N

분류 코드


2.6코드 정의

2.6.1오류 코드

code

message

설명

0


정상코드

-400

ForbiddenException

권한 없음

-500

UnauthorizedException

인증 실패

-501

InvalidSenderException

(InvalidSenderIdException,

InvalidSenderConsultStatusException)

발신 프로필 키가 유효하지 않거나 상담을 진행할 수 없음

(카카오톡 채널이 activated 상태가 아닌 경우 상담톡 이용 중 상태가 아닌 경우)

-502

InvalidSessionException

세션이 만료되었거나 존재하지 않음

-503

InvalidUserKeyException

잘못된 형식의 유저키 요청

-504

DuplicateSerialNumberException

메시지 일련번호가 중복됨

(메시지 일련번호는 CS처리를 위해 고유한 값이 부여되어야 함.)

-505

InvalidImageException(InvalidImageFormatException,InvalidImageMaxLengthException)

잘못된 이미지 전송 요청

-506

MessageLengthOverLimitException

메시지 길이 제한 오류 1000자 초과

-507

InvalidHubPartnerException

허브 파트너 키가 유효하지 않음

-508

InvalidProfileChatStatusException

채팅 기능이 비활성 상태인 경우

-509

InvalidJsonException(NoJsonBodyException, JsonParseException, NoValueJsonElementException)

잘못된 파라메터 요청

-510

InvalidMessageException(NoImageException, NoTextException, FailedToReadButtonLinkException, NoMatchedButtonUrlException, NoMandatoryButtonPropertyException)

잘못된 형식의 메시지 타입 요청

-511

BlockedUserMessageException

차단된 사용자에게 메시지 전송 요청

-512

ContractNotFoundException

유효한 상담톡 계약이 존재하지 않음

-600

FailedToSendMessageException

메시지 전송 실패

-601

InternalSystemErrorException

내부 시스템 에러