16.페르소나 챗봇 연동 문서

Edit

16.1API 개요

챗봇 과 넥서스 간 채팅 메시지를 수신/발신 하기 위헤 제공되는 API 문서입니다.
인증은 넥서스 채팅서버도 X-Bottalks-Key  를 사용하며. 채팅 종료시 까지 유지 됩니다.

16.1.1선결 조건

16.1.1.1사용자 정보는 페르소나에서 전송 할것인가?

YES
=> [채팅상담 요청 & 챗봇 로그 전송 API] 에 고객 정보 필드를 추가

16.1.1.2상담원 연결 정보 및 부가 정보 공유가 필요한가?

NO
=> [상담원 연결 API] 미사용 처리

16.1.2챗봇 API 리스트

16.1.2.1채팅상담 요청 & 챗봇 로그 전송 API

16.1.2.2챗봇에서 대화 종료시 챗봇 로그 전송 API

16.1.2.3사용자 발화 전송

16.1.2.4채팅방 종료(사용자 상담 종료 처리시 OR 만료시간이 있을경우 채팅방 만료시)

16.1.3채팅서버 API 리스트

16.1.3.1상담원 연결

16.1.3.2채팅 메시지 전송 (채팅서버 -> 챗봇)

16.1.3.3채팅방 종료

16.2챗봇 API

16.2.1채팅상담 요청 & 챗봇 로그 전송 API

16.2.1.1Request

Description

채팅상담 오픈 요청.

Method

POST

API URL

https://채팅서버 도메인 or IP/persona/reference

header

Content-Type: application/json; charset=UTF-8

키네임


타입

필수

설명

mode


string

Y

액션

tenant


string

Y

회사 ID(테넌트) , SSO 정보에 포함

botid


string

Y

챗봇 ID

roomToken


string

Y

챗봇 세션 ID

roomUid


string

Y

챗봇 세션 UID

userInfo


object

N

사용자 정보


phone

string


전화번호


name

string


이름


userid

string


사용자 ID

secretKey


string

Y

API 키 (채팅 응답 전송 시 헤더에 필요)

messages


array

Y

챗봇 대화 내역

* 기타 채팅상담 시 필요한 항목이 있을 경우 협의 후 추가.

[SAMPLE]
{
    "mode":"chat_open",
    "botid":"208dcb0651873e0",
    "roomUid":"1234456",
    "roomToken":"1961h9fsvp9trr8urcsc",
    "secretKey":"e7d77d5761319fa1cb891188adce84aff5af766ae77752d65cc1ae",
    "messages":[
        {
            "speaker":"user",
            "data":{"type":"text","msg":"Welcome"},
            "time":"2023-09-04 19:49:33"
        },
        {
            "speaker":"bot",
            "data":[
                {"type":"text","msg":"안녕하세요"},
                {"type":"button","buttons":["버튼1", "버튼2"]},
            ],
            "time":"2023-09-04 19:49:34"
        }
    ]
}

16.2.1.2Response

응답값 없음 (HTTP HEADER 200: 성공, 나머지는 실패)

200 외 코드는 추후 정의 하겠습니다.

16.2.2챗봇에서 대화 종료시 챗봇 로그 전송 API

16.2.2.1Request

Description

채팅상담 오픈 요청.

Method

POST

API URL

https://채팅서버 도메인 or IP/persona/chat_end

header

Content-Type: application/json; charset=UTF-8

키네임


타입

필수

설명

mode


string

Y

액션

tenant


string

Y

회사 ID(테넌트)

botid


string

Y

챗봇 ID

roomToken


string

Y

챗봇 세션 ID

roomUid


string

Y

챗봇 세션 UID

userInfo


object

N

사용자 정보


phone

string


전화번호


name

string


이름


userid

string


사용자 ID

secretKey


string

Y

API 키 (채팅 응답 전송 시 헤더에 필요)

messages


array

Y

챗봇 대화 내역

* 기타 채팅상담 시 필요한 항목이 있을 경우 협의 후 추가.

[SAMPLE]
{
    "mode":"chat_open",
    "botid":"208dcb0651873e0",
    "roomUid":"1234456",
    "roomToken":"1961h9fsvp9trr8urcsc",
    "secretKey":"e7d77d5761319fa1cb891188adce84aff5af766ae77752d65cc1ae",
    "messages":[
        {
            "speaker":"user",
            "data":{"type":"text","msg":"Welcome"},
            "time":"2023-09-04 19:49:33"
        },
        {
            "speaker":"bot",
            "data":[
                {"type":"text","msg":"안녕하세요"},
                {"type":"button","buttons":["버튼1", "버튼2"]},
            ],
            "time":"2023-09-04 19:49:34"
        }
    ]
}

16.2.2.2Response

응답값 없음 (HTTP HEADER 200: 성공, 나머지는 실패)

200 외 코드는 추후 정의 하겠습니다.

16.2.3사용자 발화 전송 (챗봇 -> 채팅 서버)

16.2.3.1Request

Description

채팅상담 오픈 요청.

Method

POST

API URL

https://채팅서버 도메인 or IP/persona/message

header

Content-Type: application/json; charset=UTF-8

X-Bottalks-Key: {채팅 오픈 요청시 전송된 챗봇 secretKey}

키네임

타입

필수

설명

mode

string

Y

액션(user_msg)

botid

string

Y

챗봇 ID

roomToken

string

Y

챗봇 세션 ID

roomUid

string

Y

챗봇 세션 UID

messages

array

Y

전송할 메시지 배열

time

timestamp

Y

메시지 전송 시간

messageId

string

Y

메시지 일련번호(고유값)

....




* 기타 채팅상담 시 필요한 항목이 있을 경우 협의 후 추가.

[SAMPLE] - 텍스트
{
    "mode":"user_msg",
    "botid":"208dcb0651873e0",
    "roomUid":"1234456",
    "roomToken":"1961h9fsvp9trr8urcsc",
    "messages":[{"content":"안녕하세요."}],
    "messageId":"BOT2023103100001",
    "time" : 12312312312123123
}
[SAMPLE] - 텍스트 타입 외
{
    "mode":"image",
    "botid":"208dcb0651873e0",
    "roomUid":"1234456",
    "roomToken":"1961h9fsvp9trr8urcsc",
    "secretKey":"e7d77d5761319fa1cb891188adce84aff5af766ae77752d65cc1ae",
    "messages":[
        {"url":"http://test.com/1.jpg","comment":"사진1"},
        {"url":"http://test.com/2.jpg","comment":"사진2"},
    ] ,
    "messageId":"BOT2023103100001",
    "time" : 12312312312123123
}

16.2.3.2Response

응답값 없음 (HTTP HEADER 200: 성공, 나머지는 실패)

16.2.4채팅방 종료 (챗봇 -> 채팅서버)

16.2.4.1Request

Description

채팅상담 오픈 요청.

Method

POST

API URL

https://채팅서버 도메인 or IP/persona/expired_session

header

Content-Type: application/json; charset=UTF-8

X-Bottalks-Key: {채팅 오픈 요청시 전송된 챗봇 secretKey}

키네임

타입

필수

설명

mode

string


채팅방 종료 사유

botid

string

Y

챗봇 ID

roomToken

string

Y

챗봇 세션 ID

roomUid

string

Y

챗봇 세션 UID

secretKey

string

Y

API 키 (채팅 응답 전송 시 헤더에 필요)

* 기타 채팅상담 시 필요한 항목이 있을 경우 협의 후 추가.

[SAMPLE] - 고객 채팅 종료
{
    "mode":"client",
    "botid":"208dcb0651873e0",
    "roomUid":"1234456",
    "roomToken":"1961h9fsvp9trr8urcsc",
    "secretKey":"e7d77d5761319fa1cb891188adce84aff5af766ae77752d65cc1ae",
}

16.2.4.2Response

응답값 없음 (HTTP HEADER 200: 성공, 나머지는 실패)

16.3Nexus 채팅서버 API

16.3.1상담원 연결 (채팅서버 -> 챗봇)

16.3.1.1Request

Description

채팅상담 오픈 요청.

Method

POST

API URL

https://{챗봇 ID}.chatbot.bottalks.co.kr/chatapi_cs/cs_connect

header

Content-Type: application/json; charset=UTF-8

X-Bottalks-Key: {채팅 오픈 요청시 전송된 챗봇 secretKey}

키네임

타입

필수

설명

mode

string

Y

chat_open

roomToken

string

Y

챗봇 세션 ID

roomUid

string

Y

챗봇 세션 UID

cs_id

string

Y

채팅 상담 세션 ID

info

array

N

부가정보

botid

string

Y

챗봇 ID

[SAMPLE]
{
    "mode":"chat_open",
    "botid":"208dcb0651873e0",
    "roomUid":"1234456",
    "roomToken":"1961h9fsvp9trr8urcsc",
    "secretKey":"e7d77d5761319fa1cb891188adce84aff5af766ae77752d65cc1ae",
    "csId":"client_test"
}
Response
응답값 없음 (HTTP HEADER 200: 성공, 나머지는 실패)

16.3.2상담사 채팅 응답 전송 (채팅서버 -> 챗봇 )

16.3.2.1Request

Description

채팅상담 오픈 요청.

Method

POST

API URL

https://ccaas.chatbot.bottalks.co.kr/chatapi_cs/cs_msg

header

Content-Type: application/json; charset=UTF-8

X-Bottalks-Key: {채팅 오픈 요청시 전송된 챗봇 secretKey}

키네임

타입

필수

설명

mode

string

Y

메시지 타입

(text, image, file,link)

roomToken

string

Y

챗봇 세션 ID

roomUid

string

Y

챗봇 세션 UID

botid

string

Y

챗봇 ID

messages

array

Y

챗봇 대화 내역

time

timestamp

Y

시간

messages 정의

키네임


타입

필수

설명

messages


array

Y

메시지 배열


url

string

Y

파일 URL


comment

string

Y

파일명, 링크명


size

string

N

파일사이즈


mime_type

string

N

파일 타입(MIME)


preview_url

string

N

이미지일경우 사용

Thumbnail URL

* 기타 채팅상담 시 필요한 항목이 있을 경우 협의 후 추가.

[SAMPLE] - 텍스트
{
    "mode":"text",
    "roomUid":"1234456",
    "roomToken":"1961h9fsvp9trr8urcsc",
    "messages":["안녕하세요."] 
    "time" : 12312312312123123
}
[SAMPLE] - image
{
    "mode":"image",
    "roomUid":"1234456",
    "roomToken":"1961h9fsvp9trr8urcsc",
    "messages":[
        {"url":"http://test.com/1.jpg","comment":"사진1"},
        {"url":"http://test.com/2.jpg","comment":"사진2"},
    ] ,
    "time" : 12312312312123123
}
[SAMPLE] - file
{
    "mode":"file",
    "roomUid":"1234456",
    "roomToken":"1961h9fsvp9trr8urcsc",
    "messages":[
        {
            "url":"http://test.com/1.jpg","comment":파일1", 
            "size":"100000", 
            "mime_type":"image/jpg",
            "preview_url":"http://test.com/thumbnail/1.jpg"
        },
        {
            "url":"http://test.com/2.jpg","comment":파일2", 
            "size":"200000", 
            "mime_type":"image/jpg",
            "preview_url":"http://test.com/thumbnail/2.jpg"
        }    ] ,
    "time" : 12312312312123123
}
[SAMPLE] - link button
{
    "mode":"link",
    "roomToken":"1961h9fsvp9trr8urcsc",
    "messages":[
        {"url":"http://test.com/test","comment":"링크버튼1},
        {"url":"http://test.com/test2","comment":"링크버튼2"},
    ] ,
    "time" : 12312312312123123
}

16.3.2.2Response

응답값 없음 (HTTP HEADER 200: 성공, 나머지는 실패)

16.3.3채팅방 종료 (채팅서버 -> 챗봇)

16.3.3.1Request

Description

채팅상담 오픈 요청.

Method

POST

API URL

https:/ccaas.chatbot.bottalks.co.kr/chatapi_cs/cs_end

header

Content-Type: application/json; charset=UTF-8

X-Bottalks-Key: {채팅 오픈 요청시 전송된 챗봇 secretKey}

키네임

타입

필수

설명

mode

string

Y

채팅방 종료 사유

roomToken

string

Y

챗봇 세션 ID

roomUid

string

Y

챗봇 세션 UID

botid

string

Y

챗봇 ID

* 기타 채팅상담 시 필요한 항목이 있을 경우 협의 후 추가.

[SAMPLE] - 고객 응답 없음
{
    "mode":"timeout",  // 고객 응답 없음 
    "botid":"208dcb0651873e0",
    "roomToken":"1961h9fsvp9trr8urcsc"
}
[SAMPLE] - 고객 상담 종료시
{
    "mode":"agent",  //상담사 채팅 종료시
    "botid":"208dcb0651873e0",
    "roomToken":"1961h9fsvp9trr8urcsc"
}

16.3.3.2Response

응답값 없음 (HTTP HEADER 200: 성공, 나머지는 실패)

16.4상담원 연동 API

16.4.1상담원 연결 (PBX -> 채팅서버)

16.4.1.1Request

Description

채팅상담 오픈 요청.

Method

POST

API URL

https://채팅서버/persona/chat/connect

header

Content-Type: application/json; charset=UTF-8

키네임

타입

필수

설명

sender_key

string

Y

Sender Key

user_key

string

Y

사용자 정보

uuid

string

Y

UUID 정보

agent_dn

string

N

agent DN 정보

[SAMPLE]
{
    "sender_key":"1",
    "user_key":"7511hfr3ih1c85582n1u",
    "uuid":"00FA08000100036555C976",
    "agent_dn":"30010"
}
Response
응답값 없음 (HTTP HEADER 200: 성공, 나머지는 실패)

16.4.2상담 종료 (PBX -> 채팅서버, 상담원 -> 채팅서버)

16.4.2.1Request

Description

채팅상담 오픈 요청.

Method

POST

API URL

https:/채팅서버/persona/chat/end

header

Content-Type: application/json; charset=UTF-8

키네임

타입

필수

설명

mode

string

Y

채팅방 종료 사유(agent, timeout)

sender_key

string

Y

SENDER KEY

user_key

string

Y

사용자 키

* 기타 채팅상담 시 필요한 항목이 있을 경우 협의 후 추가.

[SAMPLE] - 고객 응답 없음
{
    "mode":"timeout",  // 고객 응답 없음 
    "sender_key":"1",
    "user_key":"7511hfr3ih1c85582n1u"
}
[SAMPLE] - 고객 상담 종료시
{
    "mode":"agent",  //상담사 채팅 종료시
    "sender_key":"1",
    "user_key":"7511hfr3ih1c85582n1u"
}

16.4.2.2Response

응답값 없음 (HTTP HEADER 200: 성공, 나머지는 실패)

16.4.3상담원 채팅 (PBX -> 채팅서버)

16.4.3.1Request

Description

채팅상담 오픈 요청.

Method

POST

API URL

https://채팅서버/persona/chat/write

header

Content-Type: application/json; charset=UTF-8

키네임

타입

필수

설명

sender_key

string

Y

Sender Key

user_key

string

Y

사용자 정보

message_type

string


메시지 타입

(TX : 텍스트, IM : 이미지, FI: 일반파일, LI : 링크타입)

message

string

Y

메시지 내용 ex)"안녕하세요!"

FI, IM 일경우는 사용자에게 전달될 파일이름

url

string

Y

메지지 타입 LI, IM, FI 일경우 사용

파일 url or 버튼 링크 url

file_size

string

N

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

FI, IM 일 경우 사용

mime_type

string

N

파일 사이즈

FI, IM 일 경우 사용

preview_url

string

N

미리보기 URL (thumbanil URL)

IM일 경우 사용

[SAMPLE]

일반 메시지

{
    "sender_key":"1",
    "user_key":"7511hfr3ih1c85582n1u",
    "uuid":"00FA08000100036555C976",
    "message_type":"TX",
    "message":"안녕하세요"
}

이미지

{
    "sender_key":"1",
    "user_key":"7511hfr3ih1c85582n1u",
    "uuid":"00FA08000100036555C976",
    "message_type":"IM",
    "message":"이미지명",
    "url":"http://text.com/test.jpg",
    "mime_type":"image/jpg",
    "preview_url":"http://text.com/thumbnail/test.jpg"}

파일

{
    "sender_key":"1",
    "user_key":"7511hfr3ih1c85582n1u",
    "uuid":"00FA08000100036555C976",
    "message_type":"FI",
    "message":"파일명",
    "url":"http://text.com/test.jpg",
    "file_size":"100000",
    "mime_type":"image/jpg"
}

링크

{
    "sender_key":"1",
    "user_key":"7511hfr3ih1c85582n1u",
    "uuid":"00FA08000100036555C976",
    "message_type":"LI",
    "message":"버튼이름",
    "url":"http://text.com/smaple.html"
}
Response
응답값 없음 (HTTP HEADER 200: 성공, 나머지는 실패)