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

플랫폼 연동 - Previous

카카오톡 (카카오 i 오픈 빌더)

Next - Policy

FAQ

Last updated 10 months ago

Text Parameters	Description
score	해당 모듈의 머신러닝 모델 결과 값
name	모듈의 이름: conversation, replyReaction, replyCustom, topic 등
link	제공되는 대화 시나리오 혹은 답변의 빌더 내 주소
from	해당 대화 시나리오 혹은 답변의 이름
type	답변의 형태: text
text	답변 내용

Image Parameters	Description
url	답변으로 제공된 이미지의 주소
score	이미지셋의 경우 1.0으로 고정
name	모듈의 이름: imageSet 고정
link	제공되는 이미지셋의 빌더 내 주소
from	해당 이미지셋의 이름
type	답변의 형태: image