Custom API

어디에서나 생동감 있는 인공지능 봇과 대화해보세요😊

[Custom API]를 통해 웹페이지 및 모바일 앱에 핑퐁 빌더로 만든 봇을 연동할 수 있습니다.

Request

JSON 형식으로 사용자 발화를 보내면 핑퐁 빌더에서 생성한 적절한 답변을 받아볼 수 있습니다. 이때 문맥을 고려한 답변 제공 기능을 이용하기 위해서는 두 가지 방법으로 request를 제공해주시면 됩니다.

1. 마지막 발화(query)와 session Id 제공

아래와 같이 request는 단일 query로 보낼 때는 session Id를 꼭 같이 보내주셔야 사용자를 구분하여 대화 맥락을 고려한 자동 답변 기능을 이용할 수 있습니다.

curl -X POST \
-H "Authorization: {Authorization}" \
-H "Content-Type:application/json" \
-d "{\"request\": {\"query\": \"{query}\"}}" \
"https://builder.pingpong.us/api/builder/{botId}/integration/{version}/custom/{sessionId}"

Request 예시

curl -X POST \
-H "Authorization: Basic a2V5OjdjYWYwZmE2xjdfjFhZm24jklM1MWslkeNDslefnmE2OWU2" \
-H "Content-Type:application/json" \
-d "{\"request\": {\"query\": \"안녕하세요\"}}" \
"https://builder.pingpong.us/api/builder/1ca62a123185a612324ef24/integration/v0.2/custom/5d234ee2134aef2123"

단일 query와 session Id를 보낼 시 핑퐁 빌더로 처리되는 발화에 한해 맥락을 고려한 자동 답변 기능을 이용할 수 있습니다. 즉, 중간에 핑퐁 빌더로 처리되지 않는 기능대화가 있어서 이전 발화가 불연속적으로 주어지는 경우, 맥락을 고려한 자동 답변의 성능이 떨어질 수 있습니다.

2. dialog 형태로 제공

request를 단일 query가 아닌 여러 연속된 query를 모은 dialog 형태로 보낼 수 있습니다. 핑퐁 빌더로 처리되는 발화가 불연속적일 때(핑퐁 빌더를 다른 빌더의 fallback 용으로 사용하여 일부 기능대화가 핑퐁 빌더로 들어오지 않는 경우 등) 최대 5턴의 연속된 발화를 dialog 형태로 전달해주시면 대화 맥락을 고려한 자동 답변 기능을 이용할 수 있습니다.

마지막 {query}는 반드시 사용자 발화여야 합니다.

curl -X POST \
-H "Authorization: {Authorization}" \
-H "Content-Type:application/json" \
-d "{\"request\": {\"dialog\": [\"{query}\", \"{query}\", \"{query}\", \"{query}\", \"{query}\"]}}" \
"https://builder.pingpong.us/api/builder/{botId}/integration/{version}/custom/{sessionId}"

Request 예시

curl -X POST \
-H "Authorization: Basic a2V5OjdjYWYwZmE2xjdfjFhZm24jklM1MWslkeNDslefnmE2OWU2" \
-H "Content-Type:application/json" \
-d "{\"request\": {\"dialog\": [\"안녕?\", \"네 안녕하세요!\", \"넌 이름이 뭐야?\"]}}" \
"https://builder.pingpong.us/api/builder/1ca62a123185a612324ef24/integration/v0.2/custom/5d234ee2134aef2123"

위와 같이 단일 query가 아닌 dialog 형태로 완전하게 연속적인 query를 보내주셔야 맥락을 고려한 자동 답변의 성능이 유지됩니다.

Response

응답 포맷은 텍스트만 제공되는 형태와 이미지가 함께 제공되는 형태로 나뉩니다. 각 응답 예시는 아래와 같습니다.

텍스트 응답 예시

{
"response": {
"replies": [
{
"from": {
"score": 1.0,
"name": "conversation",
"link": "/bot/5da43e73e4b0d886932aade12e8eb4/conversation?scriptId=5dae1e2321a2e7bd88693fe8f1d",
"from": "대화 시나리오 / 안녕"
},
"type": "text",
"text": "하이! 헬로! 안녕하세요\uD83D\uDC4B"
}
]
},
"version": "1.0.0"
}

Text Parameters

Description

score

해당 모듈의 머신러닝 모델 결과 값

name

모듈의 이름: conversation, replyReaction, replyCustom, topic 등

link

제공되는 대화 시나리오 혹은 답변의 빌더 내 주소

from

해당 대화 시나리오 혹은 답변의 이름

type

답변의 형태: text

text

답변 내용

텍스트 + 이미지셋 응답 예시

{
"response": {
"replies": [
{
"from": {
"score": 0.9944276809692383,
"name": "conversation",
"link": "/bot/1ca62a123185a612324ef24/conversation?scriptId=5dae1e2321a2e7bd88693fe8f1d",
"from": "대화 시나리오 / 넌 최고야"
},
"type": "text",
"text": "그 소리를 들으려고 지금까지 열심히 했어요! 뿌듯하네요."
},
{
"image": {
"url": "https://media.tenor.com/images/03a79beae2e6b3fbbea622ccb80853c6/tenor.gif"
},
"from": {
"score": 1.0,
"name": "imageSet",
"link": "/bot/1ca62a123185a612324ef24/image_set?scriptId=5dae1e2321a2e7bd12345fe8f11",
"from": "이미지셋 / 잘난척"
},
"type": "image"
}
]
},
"version": "1.0.0"
}

Image Parameters

Description

url

답변으로 제공된 이미지의 주소

score

이미지셋의 경우 1.0으로 고정

name

모듈의 이름: imageSet 고정

link

제공되는 이미지셋의 빌더 내 주소

from

해당 이미지셋의 이름

type

답변의 형태: image