네이버 클라우드 플랫폼 챗봇 Custom API Spec. v2.0 업그레이드 안내

공지 바로가기

안녕하세요. 네이버 클라우드 플랫폼입니다.

네이버 클라우드 플랫폼의 챗봇 서비스는 고객사의 웹 기반의 페이지 및 모바일 애플리케이션에서도 챗봇을 쉽게 연동할 수 있도록 Custom API Spec.을 제공하고 있습니다.

보다 나은 서비스를 제공하기 위해 챗봇 시나리오의 기본 답변외에 멀티 링크 답변과 이미지 답변 기능이 추가되어 챗봇의 답변을 좀 더 쉽고 풍부하게 작성하실 수 있습니다.

※ 변경 내용

  • Custom API Spec. v1.2에서 Custom API Spec v2.0으로 업그레이드됩니다.

    • 메신저 연동을 하신 경우에는 자동으로 변환되어 서비스 영향이 없습니다.
  • 직접 Custom 연동을 하신 경우에는 버전 v1.2에서 v2.0으로 업그레이드가 필요합니다.

    • 만약, 기존의 시나리오를 수정하시지 않는다면 기존 답변은 정상적으로 제공됩니다.

    • 그러나, 새로운 방식의 이미지 및 캐로셀 형식으로 시나리오를 수정하신 경우에는 반드시 Custom API Spec. v2.0을 적용하셔야 서비스에서도 정상적으로 답변이 반영됩니다.

※ 대상 및 적용일

  • '18년 11월 13일부터 챗봇 서비스의 Custom API Spec. v2.0이 제공됩니다.

    • '19년 6월 30일부터 챗봇 서비스의 Custom API Spec. v1.2은 종료됩니다.

네이버 클라우드 플랫폼 챗봇 서비스의 기능 개선 및 안정적인 운영을 위해 기존에 제공하고 있는 Custom API Spec v1.2는 향후에 종료될 예정이오니 기존에 Custom API v1.2로 연동하셨던 고객 여러분께 양해 부탁드립니다.

늘 최선을 다하는 네이버 클라우드 플랫폼이 되겠습니다.

감사합니다.

챗봇 Custom API Spec.

Status: v1.2

Table of Contents

Summary

Please setting APIGW first, reference APIGW Integration Document

  • Request Path: API Gateway -> Stages -> root path '/' -> 'Invoke URL'

chatbot-02-051.png

  • Request Method: POST

  • Content-Type: application/json;UTF-8

  • Headers

name value
Content-Type "application/json;UTF-8"
  • Response Status: 200

  • Request & Response Body Example

    {
      "userId": "U47b00b58c90f8e47428af8b7bddcda3d",
      "timestamp": "12345678",
      "version": "v1",
      "content": [
        // one or more Text / Image / Link / Button / Group
      ],
      "event": "send"
    }
    
  • Model

Field Type Required Description
userId string true unique id
version string false default 'v1', protocol version
content array true Text / Image / Link / Button / Group, please reference content define
event string true "send"event is for message send, "open" event triggered when open messenger

You can quick start with some examples of full body.

Event

open

  • trigger when open messenger (Custom Messenger -> Chatbot)

    {
      "sessionId": "U47b00b58c90f8e47428af8b7bddcda3d",
      "timestamp": "12345678",
      "content": [
        // one or more Text / Image / Link / Button / Group
      ],
      "event": "open"
    }
    

send

  • send message (Custom Messenger <-> Chatbot)

    {
      "sessionId": "U47b00b58c90f8e47428af8b7bddcda3d",
      "timestamp": "12345678",
      "content": [
        // one or more Text / Image / Link / Button / Group
      ],
      "event": "send"
    }
    

Content

Text

  • contentType: text

  • Model

Field Type Required Description
type string true text
title string false top text
data.details string false text content
  • Example

    {
      "type": "text",
      "title": "short bold text",
      "data" : {
        "details" : "text content"
      }
    }
    

Image

  • contentType: image

  • Model

Field Type Required Description
type string true image
title string false opt short text
data.url string true image url
data.description string false details info of image
  • Example

      {
        "type": "image",
        "title": "opt text",
        "data" : {
        "url":"<https://docs.ncloud.com/ko/assets/security-4-1.png>",
        "description":"details info of image" }
       }
    
  • contentType: link

  • Model

Field Type Required Description
type string true link
title string false link show text, if no title, show data.url instead
data.type string true web
data.url string false link url
  • Example

    • web link: jump to url
  {
    "type": "link",
    "title": "LinkText",
    "data": {
      "type": "web",
      "url":"https://wwww.ncloud.com/..."
    }
  }

Button

  • Model
Field Type Required Description
type string true button
title string true text show on the button
data.type string true web / text
data.code string false not show, for text button type, send in reply text message
data.url string false for web link button, jump to url
  • Example:

    • web url: jump to url
    {
        "type": "button",
        "title" :"Button Title",
        "data": {
            "type": "web",
            "url": "http://www.ncloud.com"
        }
    }
    
    • text: send text button contains code
    {
        "type": "button",
        "title" :"Title to show",
        "data": {
            "code": "buttonCode",
            "type": "text"
        }
    }
    

Group

  • contentType: group

  • a group of same type contents

  • Model

Field Type Required Description
type string true group
title string false top text
data.type string true content type
data.content Content array true
  • Example:

    {
         "type" : "group",
         "title" :"Group Title Line",
         "data" : {
              "type": "link",
              "content": [
                  {
                    "type": "link",
                    "title": "link1",
                    "data" : {
                      "type": "web",
                      "url":"http://www.ncloud.com"
                    }
                  },
                  {
                    "type": "link",
                    "title": "link2",
                    "data" : {
                      "type": "web",
                      "url":"http://www.ncloud.com"
                    }
                  }
              ]
         }
    }
    

Error Response

  • Model
Field Type Required Description
code string true error code
message string false error reason
timestamp long true ms value
  • Response Http Status
code Description
200 Request successful
400 request param invalid
401 Unauthorized
403 Not authorized to access
500 Other error, specific details with error code in body
  • Error code define
code Description
1000 version not support
1001 Not found domain code
1002 check url param is invalid
  • Example

    HttpStatus = 400
    Body:
    {
      "code": "400",
      "message": "bad request",
      "timestamp": "12345678"
    }
    
    HttpStatus = 500
    Body:
    {
      "code": "1001",
      "message": "domain code test not found",
      "timestamp": "12345678"
    }
    

Examples

Text

  • UI Mock

chatbot-02-051.png

  • DM Manage

    chatbot-02-051.png

  • Message

    {
    "userId": "U47b00b58c90f8e47428af8b7bddcda3d",
    "timestamp": "12345678",
    "version": "v1",
    "content": [
      {
        "type": "text",
        "data" : {
          "details" : "text content"
        }
      }
    ],
    "event": "send"
    }
    

Image & Text + Image

  • UI Mock

    chatbot-02-051.png

  • DM Manage

chatbot-02-051.png

  • Message
{
  "userId": "U47b00b58c90f8e47428af8b7bddcda3d",
  "timestamp": "12345678",
  "version": "v1",
  "content": [
    {
      "type": "image",
      "title": "ShortTitle",
      "data" : {
        "url":"https://image.png",
        "description":"details info of image"
      }
    }
  ],
  "event": "send"
}

Text + Button

  • UI Mock

chatbot-02-051.png

  • DM Manage chatbot-02-051.png

  • Message

{
  "userId": "U47b00b58c90f8e47428af8b7bddcda3d",
  "timestamp": "12345678",
  "version": "v1",
  "content": [
    {
      "type": "group",
      "title": "text content on the top of the group",
        "data": {
        "type": "button",
        "content": [
          {
            "type": "button",
            "title": "Option 1",
            "data": {
              "type": "text",
              "code": "opt1"
            }
          },
          {
            "type": "button",
            "title": "Option 2",
            "data": {
              "type": "text",
              "code": "opt2"
            }
          }
        ]
      }
    }
  ],
  "event": "send"
}
  • UI Mock

chatbot-02-051.png

  • DM Manage

chatbot-02-051.png

  • Message
{
  "userId": "U47b00b58c90f8e47428af8b7bddcda3d",
  "timestamp": "12345678",
  "version": "v1",
  "content": [
    {
      "type": "group",
      "title": "text content on the top of the group",
        "data": {
        "type": "link",
        "content": [
          {
            "type": "link",
            "title": "Link 1",
            "data": {
              "type": "web",
              "url": "http://docs.ncloud.com/en/compute/compute-1-1-v1.html"
            }
          },
          {
            "type": "link",
            "title": "http://docs.ncloud.com",
            "data": {
              "type": "web",
              "url": "http://docs.ncloud.com"
            }
          }
        ]
      }
    }
  ],
  "event": "send"
}

Text + Image + Button

  • UI Mock

chatbot-02-051.png

  • DM Manage

chatbot-02-051.png

  • Message
{
  "userId": "U47b00b58c90f8e47428af8b7bddcda3d",
  "timestamp": "12345678",
  "version": "v1",
  "content": [
    {
      "type": "image",
      "title": "ImageTitle",
      "data" : {
        "url":"https://image.png",
      }
    },
    {
      "type": "group",
      "title": "text content on the top of the group",
        "data": {
        "type": "button",
        "content": [
          {
            "type": "button",
            "title": "Option 1",
            "data": {
              "type": "text",
              "code": "opt1"
            }
          },
          {
            "type": "button",
            "title": "Option 2",
            "data": {
              "type": "text",
              "code": "opt2"
            }
          }
        ]
      }
    }
  ],
  "event": "send"
}
  • UI Mock

chatbot-02-051.png

  • DM Manage

chatbot-02-051.png

  • Message
{
  "userId": "U47b00b58c90f8e47428af8b7bddcda3d",
  "timestamp": "12345678",
  "version": "v1",
  "content": [
    {
      "type": "image",
      "title": "ImageTitle",
      "data" : {
        "url":"https://image.png",
      }
    },
    {
      "type": "group",
      "title": "text content on the top of the group",
      "data": {
        "type": "link",
        "content": [
          {
            "type": "link",
            "title": "Link 1",
            "data": {
              "type": "web",
              "url": "http://docs.ncloud.com/en/compute/compute-1-1-v1.html"
            }
          },
          {
            "type": "link",
            "title": "http://docs.ncloud.com",
            "data": {
              "type": "web",
              "url": "http://docs.ncloud.com"
            }
          }
        ]
      }
    }
  ],
  "event": "send"
}

Multi Images

  • UI Mock

chatbot-02-051.png

  • DM Manage

chatbot-02-051.png

  • Message
{
  "userId": "U47b00b58c90f8e47428af8b7bddcda3d",
  "timestamp": "12345678",
  "version": "v1",
  "content": [
    {
      "type": "group",
      "title": "text content of the image group",
      "data": {
        "type": "image",
        "content": [
          {
            "type": "image",
            "title": "Image Title 1",
            "data": {
              "url": "https://image/1.png"
            }
          },
          {
            "type": "image",
            "title": "Image Title 2",
            "data": {
              "url": "https://image/2.png"
            }
          }
        ]
      }
    }
  ],
  "event": "send"
}
  • UI Mock

chatbot-02-051.png

  • DM Manage

chatbot-02-051.png

  • Message
{
  "userId": "U47b00b58c90f8e47428af8b7bddcda3d",
  "timestamp": "12345678",
  "version": "v1",
  "content": [
    {
      "type": "group",
      "title": "text content of the image group",
      "data": {
        "type": "image",
        "content": [
          {
            "type": "image",
            "title": "Image Title 1",
            "data": {
              "url": "https://image/1.png"
            }
          },
          {
            "type": "image",
            "title": "Image Title 2",
            "data": {
              "url": "https://image/2.png"
            }
          }
        ]
      }
    },
    {
      "type": "group",
      "data": {
        "type": "link",
        "content": [
          {
            "type": "link",
            "title": "Link 1",
            "data": {
              "type": "web",
              "url": "http://docs.ncloud.com/en/compute/compute-1-1-v1.html"
            }
          },
          {
            "type": "link",
            "title": "http://docs.ncloud.com",
            "data": {
              "type": "web",
              "url": "http://docs.ncloud.com"
            }
          }
        ]
      }
    }
  ],
  "event": "send"
}

연관 정보 바로가기

도메인 생성, 대화 목록과 컴포넌트 관리 및 통계 관리와 관련하여 아래 사용 가이드를 참고하실 수 있습니다.

""에 대한 건이 검색되었습니다.

    ""에 대한 검색 결과가 없습니다.

    처리중...