목차

액션메소드 사용 가이드

챗봇에서 외부의 시스템의 데이터를 연동하는 방법은 액션메소드(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"
        },
        "userVariables": {
          "사용자 변수 이름": {
            "value": "사용자 변수에 저장된 값",
            "typ": "사용자 변수 타입(TEXT,NUMBER 중에 선택됩니다)"
          }
        }
      }
    }
    
유형 필수 설명
actionMethod Object Y 액션메소드의 정보가 들어있습니다
actionMethod.name String Y actionMethod의 이름입니다
actionMethod.methods Array[Object] N 메소드 정보가 들어있습니다
답변에 포함 돼 있던 동일한 이름의 액션메소드 정보를 모아서 한번에 요청합니다
actionMethod.methods.args Array[String] N 액션메소드에 포함 돼 있던 arguments 들의 정보입니다
actionMethod.methods.variableName String N 액션메소드 . 뒤에 오는 부분입니다
userInfo Object Y 유저의 정보가 담겨있습니다
userInfo.id String Y 유저의 아이디가 담겨있습니다
각 메신저들로 부터 받은 값 입니다
userInfo.key String Y 서빙엔진 내부에서 사용하는 유저 고유의 키를 해시한 값 입니다
userInfo.query String Y 유저가 이번턴에 입력한 발화입니다
userInfo.entities Map[String, String] N 유저의 발화에서 추출된 엔티티 정보가 담겨있습니다
Map(entity code -> user input)
userInfo.taskEntities Map[String, String] N 태스크를 진행하면서 채워진 슬롯에 어떤 엔티티가 담겨졌는지에 대한 정보가 담겨있습니다
Map(entity name -> user input or representative) 슬롯 설정에 따라 사용자의 입력이나 대표어가 value로 들어가 있습니다
userVariables Map[String, String or Long, String] N 세션 내에 저장된 사용자 변수에 대한 정보가 담겨있습니다.
userVariables.value String or Long Y 사용자 변수에 저장된 값 입니다. 텍스트나 숫자가 올 수 있습니다.
userVariables.typ String Y 사용자 변수의 타입이 무엇인지 명시합니다.
  • 응답 형식은 다음과 같습니다.

    {
      "data": [
        {
          "variableName": "변수명에 해당하는 부분입니다",
          "value": "variableName에 해당하는 변수를 어떤 값으로 치환할지를 결정합니다"
        }
      ],
      "userVariable": [
        {
          "name": "사용자 변수 이름입니다",
          "value": "사용자 변수에 저장할 값입니다",
          "type": "사용자 변수의 타입입니다",
          "action": "동작을 지정합니다",
          "valueType": "저장할 값의 타입입니다"
        }
      ]
    }
    

    | 값 | 유형 | 필수 | 설명 | | ---- | ------- | ----------- | --------------------------| | data | Array[Object] | Y | actionMethod의 응답 값이 들어있는 필드입니다 | | | data.variableName | String | Y | 변수명에 해당하는 부분입니다 | | | data.value | String | Y | variableName에 해당하는 변수를 어떤 값으로 바꿔줄지 결정합니다 | | | userVariable | Array[Object] | N | 사용자 변수를 변경하기 위하여 사용할 수 있습니다. | | | userVariable.name | String | Y | 사용자 변수명 입니다 | | | userVariable.value | String or Long | Y | 값 입니다. 텍스트나 숫자가 올 수 있습니다. | | | userVariable.type | String | Y | userVariable의 타입이 무엇인지 명시합니다. 텍스트일 경우 TEXT, 숫자일 경우 NUMBER 를 입력합니다 | | | userVariable.action | String | Y | 동작을 지정합니다. EQ, ADD, SUB가 올 수 있으며, 텍스트 타입일 경우 EQ만 가능합니다. | | | userVariable.valueType | String | Y | userVariable.value 의 타입이 무엇인지 명시합니다. | |

  • 이렇게 생성한 액션메소드는 답변 필드에 입력하여, 답변이 응답되는 타이밍에 호출하게 됩니다.

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

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

LINE PAY와 NAVER PAY

LINE PAY와 NAVER PAY 액션 메소드를 통해 간편하게 LINE PAY, NAVER PAY로 결제하는 시나리오를 구성할 수 있습니다. LINE PAY 연동 가이드NAVER PAY 연동 가이드를 참고하여 LINE PAY, NAVER PAY 서비스를 연동한 후에 사용해주세요.

  • 가격 입력형

    chatbot-2-8-06.png

    • 입력된 가격으로 LINE PAY/NAVER PAY 결제를 진행합니다. 가격의 변동이 없는 상품을 결제할 때 활용하는 것을 권장합니다.

    • 이름: 가격 입력형의 경우 액션 메소드의 이름을 직접 입력하지 않습니다. 가격정보와 상품명을 입력하면 액션 메소드 이름이 자동완성됩니다.

    • 가격정보: 결제할 가격을 입력합니다. LINE PAY의 기준 통화는 엔(¥), NAVER PAY의 기준 통화는 원(₩) 입니다.

    • 상품명: 결제할 상품의 이름을 입력합니다.

  • API 연동형

    chatbot-03-029.png

    • 입력된 외부 URL을 호출하여 확인된 가격으로 LINE PAY/NAVER PAY 결제를 진행합니다. 가격이 고정되어 있지 않거나, 사용자가 선택한 슬롯 정보에 따라 가격이 변동되는 경우 활용하는 것을 권장합니다.
    • 이름: 액션 메소드의 이름을 입력합니다.
    • URL: 가격정보를 확인할 수 있는 외부 URL을 입력합니다.

예를 들어 사용자가 콤비네이션 피자 S사이즈 2판을 주문하였다면, 아래의 슬롯 정보를 외부 URL로 전달합니다. Response로 돌아오는 값이 '49900'이라면, 챗봇은 49,900원을 LINE PAY/NAVER PAY를 통해 결제합니다.

@피자 : 콤비네이션 피자
@피자 사이즈 : S사이즈
@피자 수량 : 2판

CEK Request 전달

CEK Request를 전부 bypass 해주는 액션메소드입니다.

chatbot-03-030.png

  • CEK Request 전달 액션메소드는 JSON(POST) 방식만 지원합니다.
  • 이름 : 액션메소드의 이름을 입력합니다.
  • URL : CEK Request를 전달할 URL을 입력합니다.
  • CEK 에서 전달된 Request body를 전달합니다.
  • 메신저가 Clova인 경우에만 동작하며, 챗봇빌더의 수동테스트 및 자동테스트에서는 동작하지 않습니다.

Built in 액션메소드

${`PreviousChatbot} 액션메소드는 챗봇의 이전 발화 및 컨텍스트를 활용할 수 있는 액션메소드입니다. 해당 액션메소드는 [대화 로그 임시 저장 설정]를 활성화 한 경우에만 사용 가능하며, 메신저 설정을 CLOVA로 설정하였거나 AiCall도메인에서만 답변에 입력 가능합니다.

chatbot-1-017.png

chatbot-1-018.png

①${`previousChatbotAnswer}
  • 마커가 표시된 답변 중 가장 최근에 응답한 챗봇의 답변을 다시 불러와 응답할 수 있습니다.
  • 이때 이전 대화의 컨텍스트는 따르지 않으며, 현재 대화의 컨텍스트 설정을 따릅니다.
②${`previousChatbotContext}
  • 마커가 표시된 이전 대화의 컨텍스트 설정을 따릅니다.
  • 이때 현재 대화의 컨텍스트는 따르지 않습니다.
③${`previousChatbotAnswerContext}
  • 마커가 표시된 이전 대화의 챗봇 답변과 컨텍스트를 불러올 수 있습니다.
  • 이때 현재 대화의 컨텍스트는 따르지 않습니다.

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

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

    처리중...