목차

액션메소드 사용 가이드

챗봇에서 외부의 시스템의 데이터를 연동하는 방법은 액션메소드(ActionMethod)를 통해서 가능합니다.

중요 !

  • 액션메소드를 유용하게 사용하시려면 REST API 호출 등 사전 개발 지식이 필요합니다.
  • 또한 챗봇의 액션메소드 호출에 응답할 수 있는 Backend System 환경 준비가 필요합니다. (챗봇 서비스와 연동하는 고객의 Backend System 환경이 모두 다르기 때문입니다.)

CLOVA Chatbot 서비스에서는 액션메소드 GEP/POST 스펙을 제공하지만, 이것을 연동하도록 Backend 서버를 구현하는것은 고객님의 개발영역이며, CLOVA Chatbot 서비스 제공 범위에 포함되지 않습니다.

개발 편의성을 높이기 위해 액션메소드에서 어떤 형식으로 Backend Server로 GET/POST를 보내는지 액션메소드 Request를 확인할 수 있는 방법(echo)을 제공합니다.

액션메소드 이해하기

액션 메소드를 사용할 때는 챗봇에서 Entity 값을 정의하고, Entity에 매핑된 사용자의 입력값을 함께 전송하게 됩니다. 사용자가 입력한 값(엔티티에 매핑된 값)을 외부의 Backend Server와 연동하기 위한 방법을 제공하는 것입니다.

즉, 엔티티로 인식된 값정보를 Backend Server로 전송하여 처리하거나, 그 정보를 기반으로 조회하여 사용자에게 답변을 해야 하는 경우에 활용됩니다.

또한 Backend Server에서는 액션메소드 호출시 함께 전송되는 파라미터들을 처리하여 어떤 응답을 줄지 미리 설계하여야 합니다.

액션메소드의 파라미터

액션 메소드를 통해서 BackendSystem에 정보를 보내려면 정의된 파라미터 형식이 필요합니다. 이때 '엔티티' 가 사용됩니다.

사전 정의된 entity 는 사용자의 데이터를 매핑할 key 이며, 액션 메소드 사용을 위해선 '엔티티'가 필수로 함께 정의되고 동작해야 합니다.

사전 정의된 entity 들을 액션메소드에서도 사용할 수 있습니다.

  • 도메인 엔티티 : 사용자가 정의한 엔티티입니다.
  • 시스템 엔티티 : 시스템에 등록된 공통 엔티티입니다.
  • API 엔티티 : API를 통해 외부 DB에 저장된 엔티티 데이터를 사용할 수 있습니다.

액션메소드 사용 예시

간단한 액션메소드 사용 예시를 들어보겠습니다.

먼저, ${피자주문업데이트}라는 액션메소드를 만듭니다.

예를 들어 피자수량' 이라는 도메인 엔티티를 미리 정의해 놓았고, 피자수량을 묻는 질문에 사용자가 '2판' 이라고 답을하였습니다.

이 경우 챗봇에서는 'entitykey'='entityvalue' 형태로 '피자수량'='2판'의 정보가 만들어 집니다.

입력된 정보를 ActionMethod를 통해서 서버에 보낼때는 액션메소드 ${피자주문업데이트}를 호출하게 됩니다.

액션메소드 ${피자주문업데이트}의 호출을 위해선 기정의된 Backend System의 호출 URL을 설정해야합니다.

당장 확인을 위해 echo기능을 통해 ActionMethod V1.0 , Get방식으로 전달 할 경우 다음과 같이 할 수 있습니다

parameter1에 피자수량 entity의 값 '2판'을 넣어서 보내느경우,

다음과 같이 parameter1=$[피자수량]으로 설정합니다.

ex) http://chatbot.ncloud.com/?parameter1=$[피자수량]

실제 호출시 $[피자수량]은 '2판'으로 대체되게 됩니다.

http://chatbot.ncloud.com/?parameter1=2판

또한 , ${피자주문업데이트} 액션 메소드를 호출할 때 GET/POST 방식의 Http header( X-KAA-USERENTITY)에도 entity정보가 포함됩니다. (아래 ActionMethod 상세 설명에서 자세히 설명됩니다. )

이렇게 액션 메소드에 entity 매핑된 정보가 전달된 후에 액션메소드가 호출이 되면 챗봇에서는 BackendSystem 서버에서 주는 응답을 기다립니다. ActionMethod의 호출 timeout 기본 설정은 200ms 입니다.

Backend System에서 ActionMethod의 응답으로 '주문(업데이트)완료'라는 응답을 전달합니다.

이렇게 호출된 액션메소드는 답변 필드에 입력된 대로, 답변이 응답되는 타이밍에 호출하게 됩니다.

  • 고객 답변 필드에 입력 : ${피자주문업데이트} 되었습니다.
  • 실제 챗봇 답변 : 주문(업데이트)완료 되었습니다.

액션메소드 상세 스펙

액션메소드 는 2가지의 spec을 제공합니다.

Version 설명 예시
액션메소드 v1.0 한번의 호출로 한번의 값 만을 받을 수 있음 , GET/POST 방식 제공 예시 : "현재 정자동의 날씨는 ${weather}도입니다."
액션메소드 v 2.0 한번의 호출로 복수의 값을 받을 수 있음 , POST 방식 제공 예시 : " ${membership.name} 고객님의 잔여포인트는 ${membership.point} 포인트 입니다."

액션 메소드 V1.0

액션 메소드는 ${ActionMethodName}의 형태로 정의됩니다.

  • GET 방식

    chatbot-03-021.png

    • 이름 : 액션메소드의 이름을 입력합니다.

    • URL : 호출할 URL을 입력합니다.

    • 응답 형식은 다음과 같습니다.

      HttpMethod: GET
      Http Headers: {
        X-KAA-USERENTITY=test_date%3dsaturday%26test_time%3d3o%27clock%26test_num%3d2people, 
        X-KAA-USERKEY=4d4cf7425f5b4769807fb4cba66bd987,
        X-KAA-USERMSG=%E3%85%87,
        X-KAA-USERID=9ff4-b49e74ea22e4
      }
      body ={}
      
      • X-KAA-USERKEY: 해시된 유저 키 값을 전달합니다
      • X-KAA-USERENTITY: 태스크가 종료됐거나, 슬롯이 진행중일 때, 등장한 엔티티 정보가 담겨있습니다 엔티티키=엔티티값&엔티티키=엔티티값&... 과 같은 형식으로 들어 있으며 utf-8 로 인코딩 돼 있습니다.
      • X-KAA-USERMSG: 사용자의 발화가 담겨있습니다. 주관식 폼이 등장했을 때, 유저가 입력했을 경우만 동작합니다. utf-8로 인코딩 돼 있습니다
      • X-KAA-USERID: 사용자의 original userId가 담겨 있습니다.
      • X-KAA-CLOVA-OAUTH-ACCESS-TOKEN: Clova 플랫폼으로 요청이 들어올 경우 해당 도메인이 외부인증을 사용하고 있다면, 인증 토큰이 Clova요청에 담겨져 오게 됩니다. 해당 값을 유통하게 설정한 액션메소드를 호출한 경우, 이 해더를 통해 해당 토큰값을 전달합니다.
      • X-KAA-SESSION-ATTRIBUTES: ActionMethod의 응답값으로 이 값을 키로한 헤더값이 있다면 엔진은 잠시동안 해당 값을 기억하고 있다가, 이 값을 전달해달라는 플래그가 on인 액션메소드가 호출됐을 경우 해더에 받았던 값을 그대로 담아 전달합니다
    • 이렇게 생성한 액션메소드는 답변 필드에 입력하여, 답변이 응답되는 타이밍에 호출하게 됩니다.

      • 예를 들어 답변을 "현재 정자동의 날씨는 ${weather}도입니다."라고 정의한 경우, ${weather}의 값은 정의한 URL을 호출해서 Response로 돌아오는 정보입니다. 이 값이 '24'이면 챗봇은 "현재 정자동의 날씨는 24도입니다."라고 답변합니다.
      • 단, 액션메소드V1.0은 한 답변에 최대 2개까지 입력 가능합니다.
  • JSON(POST) 방식

    chatbot-03-022.png

  • JSON(POST) 방식은 GET 방식과 동일하나, URL 호출에 데이터를 포함하여 보낼 수 있습니다. 데이터를 보내는 형식은 JSON 형태입니다.

  • 요청 형식은 다음과 같습니다.

    HttpMethod:  POST
    Http Headers: {
      X-KAA-USERENTITY=test_date%3dsaturday%26test_time%3d3o%27clock%26test_num%3d2people, 
      X-KAA-USERKEY=4d4cf7425f5b4769807fb4cba66bd987,
      X-KAA-USERMSG=%E3%85%87,
      X-KAA-USERID=9ff4-b49e74ea22e4
    }
    body ={"state": "korea", "country": "seoul"}
    
  • 만약 액션메소드V1.0을 테스트하고싶으시다면, echo호출을 클릭해주세요.
  • 액션 메소드V1.0은 엔티티 데이터 외에도 특정 값을 함께 전송할 수 있습니다.

  • Clova OAuth Access Token 설정을 활성화하여 Clova Extension에서 인증된 사용자 계정의 Access token을 전달할 수 있습니다.

  • Session Attributes 설정을 활성화하여 특정 문자열을 X-KAA-SESSION-ATTRIBUTES 헤더에 포함하여 전달할 수 있습니다. 이때 문자열은 UTF-8로 URL 인코딩 되어야 합니다.

    • 챗봇서버가 호출한 액션 메소드 응답값의 헤더에 X-KAA-SESSION-ATTRIBUTES 값이 존재한다면, 챗봇서버는 해당 문자열을 각 유저별로 캐싱해둡니다
    • 액션 메소드 생성 시 Session Attributes 설정을 활성화하였다면 가장 최근에 캐싱된 문자열을 X-KAA-SESSION-ATTRIBUTES 헤더에 포함하여 전달합니다.

액션 메소드 V2.0

액션메소드V1.0과의 차이점은 한번의 호출로 복수의 값을 받을 수 있다는 점입니다.

chatbot-03-025.png

  • 액션메소드V2.0은 JSON(POST) 방식만 지원합니다.

  • 이름 : 액션메소드의 이름을 입력합니다.

  • URL : 호출할 URL을 입력합니다.

  • 요청 형식은 다음과 같습니다.

    {
      "actionMethod": {
        "name": "액션메소드이름입니다",
        "methods": [
          {
            "args": [
              "arg1",
              "age2"
            ],
            "variableName": "답변에 포함된 변수명입니다1"
          },
          {
            "variableName": "답변에 포함된 변수명입니다2"
          }
        ]
      },
      "userInfo": {
        "id": "메신저로부터 받은 사용자의 아이디가 담겨있습니다",
        "key": "서빙 엔진 내부에서 사용하는 사용자의 고유 키를 해시한 값입니다",
        "query": "사용자가 이번 턴에 입력한 발화입니다",
        "entities": {
          "엔티티코드1": "사용자가 입력한 엔티티1",
          "엔티티코드2": "사용자가 입력한 엔티티2"
        },
        "taskEntities": {
          "엔티티이름1": "태스크의 슬롯에 채워진 엔티티1",
          "엔티티이름2": "태스크의 슬롯에 채워진 엔티티2"
        }
      }
    }
    
  • 응답 형식은 다음과 같습니다.

    {
      "data": [
        {
          "variableName": "변수명에 해당하는 부분입니다",
          "value": "variableName에 해당하는 변수를 어떤 값으로 치환할지를 결정합니다"
        }
      ]
    }
    
  • 이렇게 생성한 액션메소드는 답변 필드에 입력하여, 답변이 응답되는 타이밍에 호출됩니다.

    • 답변에 액션메소드V2.0을 입력할 때는 $2{액션메소드2이름} 또는 $2{액션메소드2이름.변수명} 의 형식으로 입력합니다.
    • 예를 들어, 답변을 " ${membership.name} 고객님의 잔여포인트는 ${membership.point} 포인트 입니다."라고 정의한 경우 ${membership.name}와 ${membership.point}의 값은 정의한 URL을 호출해서 Response로 돌아오는 variableName의 value입니다. name 의 vlaue가 홍길동, point 의 value가 1000 이었다면, 챗봇은 "홍길동 고객님의 잔여포인트는 1000포인트 입니다."라고 답변합니다.
  • 만약 액션메소드V2.0을 테스트하고싶으시다면, echo호출을 클릭해주세요.

    • $2{액션메소드이름.method} 를 입력하는 경우 POST를 에코해줍니다.
    • $2{액션메소드이름.body} 를 입력하는 경우 body를 에코해줍니다.

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

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

    처리중...