액션 메소드
    • PDF

    액션 메소드

    • PDF

    기사 요약

    Classic/VPC 환경에서 이용 가능합니다.

    챗봇에서 외부의 시스템의 데이터를 연동하려면 액션 메소드(ActionMethod)를 활용합니다. 액션 메소드를 활용하면 API를 호출하거나, API 호출 시 사용자와의 대화에서 분석된 내용을 전달하거나, API에서 리턴된 결과를 받아 답변하는데 활용할 수 있습니다. 예를 들어 가격 정보, 사용자 정보, 날씨 정보와 같은 가변적인 데이터를 데이터 베이스에서 실시간으로 가져와서 답변으로 제공할 수 있습니다.
    생성한 액션 메소드는 ${ActionMethodName} 형식으로 정의하여 사용합니다. 대화의 답변 등록 시 사용하려는 액션 메소드를 {ActionMethodName} 형식으로 입력하면, 해당 답변이 응답되는 시점에 액션 메소드를 호출할 수 있습니다.

    지원하는 액션 메소드는 다음과 같습니다.

    • 액션 메소드V1.0
    • 액션 메소드V2.0
    • LINE PAY
    참고
    • 액션 메소드를 유용하게 사용하려면 REST API 호출과 같은 사전 개발 지식이 필요합니다. 챗봇 서비스를 연동하는 고객의 Backend System 환경이 모두 다르기 때문에 챗봇의 액션 메소드 호출에 응답할 수 있는 Backend System 환경을 준비해야 합니다.
    • CLOVA Chatbot 서비스에서는 액션 메소드 GET/POST 스펙을 제공하고 있지만, 이것을 연동할 수 있도록 Backend 서버를 구현하는 것은 고객님의 개발 영역이며, CLOVA Chatbot 서비스 제공 범위에 포함되지 않습니다.
    • 개발 편의성을 높이기 위해 액션 메소드에서 어떤 형식으로 Backend Server로 GET/POST를 보내는지, 액션 메소드 Request를 확인할 수 있는 방법(echo)을 제공합니다.
    주의

    액션 메소드의 호출 Timeout 기본값은 200ms입니다. 호출 timeout 값은 직접 변경할 수 없으며, 변경하려면 고객 센터로 문의해 주십시오.

    액션 메소드 파라미터

    액션 메소드를 통해서 Backend System에 정보를 보내려면 정의된 파라미터 형식이 필요합니다. 이때 '엔티티'가 사용됩니다. 사전에 정의된 엔티티는 사용자의 데이터를 매핑할 key이며, 액션 메소드를 사용하기 위해서는 엔티티가 반드시 함께 정의되고 동작해야 합니다. 사전 정의된 엔티티들을 액션 메소드에서도 사용할 수 있습니다.

    액션 메소드 버전별 스펙

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

    액션 메소드 V1.0

    액션 메소드를 생성하기 전에 액션 메소드에서 활용할 도메인 엔티티를 생성해 주십시오. 생성된 액션 메소드를 답변 필드에 입력하면, 답변 응답 시 해당 액션 메소드를 호출합니다.
    예를 들어, 답변을 "현재 정자동의 날씨는 ${weather}도입니다."라고 정의한 경우, ${weather}의 값은 액션 메소드에서 정의한 URL을 호출하여 Response로 돌아오는 정보입니다. 이 값이 '24'이면 챗봇은 "현재 정자동의 날씨는 24도입니다."라고 답변합니다. 단, 액션 메소드 V1.0은 한 개의 답변에 최대 2개만 입력 가능합니다.

    GET 방식으로 액션 메소드 생성

    GET 방식으로 액션 메소드를 생성하는 방법은 다음과 같습니다.

    1. 네이버 클라우드 플랫폼의 콘솔에서 Services > CLOVA Chatbot > Domain 메뉴를 차례대로 클릭해 주십시오.
    2. 원하는 도메인의 [빌더 실행하기] 버튼을 클릭하여 챗봇 빌더를 실행해 주십시오.
    3. 챗봇 빌더에서 액션 메소드 메뉴를 클릭해 주십시오.
    4. 유형을 액션 메소드 V1.0, GET으로 선택하고, 이름 필드에 액션 메소드의 이름을 입력해 주십시오.
    5. URL 필드에 호출할 URL을 입력해 주십시오.
      • $를 입력하면 등록된 엔티티 목록이 나타나고, 엔티티 목록에서 엔티티를 선택하여 추가 가능
      • [echo 호출] 버튼 클릭 시 테스트 API가 자동으로 입력됨. 해당 액션 메소드 호출 시 챗봇 엔진에서 외부 API 서버로 전달되는 Request가 그대로 표시되어, 어떤 방식으로 Request되는지 확인 가능
        chatbot-chatbot-3-4_get01_ko
    6. 값 전송 옵션을 선택해 주십시오.
      • Session Attributes: UTF-8로 인코딩된 특정 문자열을 X-KAA-SESSION-ATTRIBUTES 헤더에 포함하여 전달 가능
    7. [저장] 버튼을 클릭해 주십시오.
      • 생성한 액션 메소드는 답변 입력 시 ${액션메소드이름}의 방식으로 활용 가능

    응답 형식

    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-TOKENCLOVA 플랫폼으로 요청이 들어올 경우, 해당 도메인이 외부 인증을 사용하고 있다면 인증 토큰이 CLOVA요청에 담겨 오게 됨. 해당 값을 유통하도록 설정한 액션 메소드를 호출한 경우, 이 헤더를 통해 해당 토큰값을 전달함
    X-KAA-SESSION-ATTRIBUTES액션 메소드의 응답값으로 이 값을 키로 한 헤더값이 있다면 엔진은 잠시 해당 값을 기억하고 있다가, 이 값을 전달해 달라는 플래그가 on인 액션 메소드가 호출됐을 경우, 헤더에 받았던 값을 그대로 담아 전달함

    JSON(POST) 방식으로 액션 메소드 생성

    JSON(POST) 방식은 GET 방식과 동일하나, URL 호출에 데이터를 포함하여 보낼 수 있습니다. 데이터를 보내는 형식은 JSON 형태입니다. 엔티티 데이터 외에도 특정 값을 함께 전송할 수 있습니다.
    POST 방식으로 액션 메소드를 생성하는 방법은 다음과 같습니다.

    1. 네이버 클라우드 플랫폼의 콘솔에서 Services > CLOVA Chatbot > Domain 메뉴를 차례대로 클릭해 주십시오.
    2. 원하는 도메인의 [빌더 실행하기] 버튼을 클릭하여 챗봇 빌더를 실행해 주십시오.
    3. 챗봇 빌더에서 액션 메소드 메뉴를 클릭해 주십시오.
    4. 유형을 액션 메소드 V1.0, POST로 선택해 주십시오.
    5. 이름 필드에 액션 메소드의 이름을 입력해 주십시오.
    6. URL 필드에 호출할 URL을 입력해 주십시오.
      • $를 입력하면 등록된 엔티티 목록이 나타나고, 엔티티 목록에서 엔티티를 선택하여 추가 가능
      • [echo 호출] 버튼 클릭 시 테스트 API가 자동으로 입력됨. 해당 액션 메소드 호출 시 챗봇 엔진에서 외부 API 서버로 전달되는 Request가 그대로 표시되어, 어떤 방식으로 Request되는지 확인 가능
    7. 데이터 필드에 JSON 형식을 갖추어 매핑할 엔티티 이름을 입력해 주십시오.
      chatbot-chatbot-3-4_post01_ko
    8. 값 전송 옵션을 선택해 주십시오.
      • Session Attributes: X-KAA-SESSION-ATTRIBUTES 헤더에 문자열을 인코딩해서 담아두면, 액션 메소드 호출 시 X-KAA-SESSION-ATTRIBUTES에 있는 값을 챗봇 엔진이 캐싱해 둠. Session Attributes 옵션이 활성화된 액션 메소드를 호출할 경우, 캐싱해 둔 X-KAA-SESSION-ATTRIBUTES에 저장된 문자열을 같이 전달함
    9. [저장] 버튼을 클릭해 주십시오.
      • 생성한 액션 메소드는 답변 입력 시 ${액션메소드이름}의 방식으로 활용 가능

    요청 형식

    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"} 
    
    항목설명
    X-KAA-USERKEY해시된 유저 키 값 전달
    X-KAA-USERENTITY태스크가 종료됐거나 슬롯이 진행 중일 때 등장한 엔티티 정보가 담겨 있음
    엔티티키=엔티티값&엔티티키=엔티티값&... 과 같은 형식으로 들어 있으며 utf-8로 인코딩 됨
    X-KAA-USERMSG사용자의 발화가 담겨 있음. 주관식 폼이 등장했을 때, 유저가 입력했을 경우만 동작. utf-8로 인코딩 됨
    X-KAA-USERID사용자의 original userId가 담겨 있음
    X-KAA-SESSION-ATTRIBUTES액션 메소드의 응답값으로 이 값을 키로한 헤더값이 있다면 엔진은 잠시 동안 해당 값을 기억하고 있다가, 이 값을 전달해달라는 플래그가 on인 액션 메소드가 호출됐을 경우, 헤더에 받았던 값을 그대로 담아 전달함

    액션 메소드 V2.0

    액션 메소드 V2.0이 액션 메소드 V1.0과 다른 점은 한 번의 호출로 여러 개의 값을 받을 수 있다는 점입니다.
    예를 들어, 답변 필드에 "${membership.name} 고객님의 잔여 포인트는 ${membership.point}포인트입니다."라고 정의한 경우 ${membership.name}와 ${membership.point}의 값은 정의한 URL을 호출해서 Response로 돌아오는 variableName의 value입니다. name의 vlaue가 홍길동, point 의 value가 1000 이었다면, 챗봇은 "홍길동 고객님의 잔여포인트는 1000포인트 입니다."라고 답변합니다.

    참고
    • 액션 메소드V2.0은 JSON(POST) 방식만 지원합니다.
    • 답변에 액션 메소드V2.0을 입력할 경우, $2{액션 메소드2이름} 또는 $2{액션 메소드2이름.변수명}의 형식으로 입력합니다.

    POST 방식으로 액션 메소드 V2.0를 생성하는 방법은 다음과 같습니다.

    1. 네이버 클라우드 플랫폼의 콘솔에서 Services > CLOVA Chatbot > Domain 메뉴를 차례대로 클릭해 주십시오.
    2. 원하는 도메인의 [빌더 실행하기] 버튼을 클릭하여 챗봇 빌더를 실행해 주십시오.
    3. 챗봇 빌더에서 액션 메소드 메뉴를 클릭해 주십시오.
    4. 유형을 액션 메소드 2.0, POST로 선택해 주십시오.
    5. 이름 필드에 액션 메소드의 이름을 입력해 주십시오.
    6. URL 필드에 호출할 URL을 입력해 주십시오.
      • $를 입력하면 등록된 엔티티 목록이 나타나고, 엔티티를 선택하여 추가할 수 있습니다.
      • [echo 호출] 버튼을 클릭하면 액션 메소드V2.0 테스트 가능
        • $2{액션 메소드이름.method}를 입력하는 경우, method를 에코함(POST가 리턴됨)
        • $2{액션 메소드이름.body}를 입력하는 경우, body를 에코함
          chatbot-chatbot-3-4_post02_ko
    7. [저장] 버튼을 클릭해 주십시오.
      • 생성한 액션 메소드는 답변 입력 시 $2{액션메소드2이름} 또는 $2{액션메소드2이름.변수명} 형식으로 입력하여 활용 가능

    요청 형식

    {
      "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": "사용자 변수에 담겨진 값",
            "type": "사용자 변수 타입(TEXT, NUMBER, JSON이 올 수 있습니다)"
          }
        }
      }
    }
    
    타입필수설명
    actionMethodObjectY액션 메소드의 정보
    actionMethod.nameStringY현재 요청하는 액션 메소드 이름
    actionMethod.methodsArray[Object]N메소드 정보
    답변에 포함되어 있던 동일한 이름의 액션 메소드 정보를 모아서 한 번에 요청
    actionMethod.methods.argsArray[String]N임의의 아규먼트를 넣어둘 수 있음. 존재할 경우 해당 아규먼트를 담아 보냄.
    <예시> $2{name(arg1, arg2).variableName}
    actionMethod.methods.variableNameStringN액션 메소드의 변수명. 액션 메소드의 . 뒤에 오는 부분을 의미.
    userInfoObjectY유저의 정보가 담겨 있음
    userInfo.idStringY유저의 아이디가 담겨 있음. 각 메신저로부터 받은 값
    userInfo.keyStringY서빙 엔진 내부에서 사용하는 사용자 고유의 키를 해시한 값
    userInfo.queryStringY유저가 현재 턴에 입력한 발화
    userInfo.entitiesMap[String, String]N유저의 발화에서 분석된 엔티티 정보가 담겨 있음
    - Map(entity code -> user input)"
    userInfo.taskEntitiesMap[String, String]N- 태스크가 완료된 경우, 해당 태스크에서 채워진 슬롯 값이 포함됨
    - Map(entity name -> user input or representative) 슬롯 설정에 따라 사용자의 입력이나 대표어가 value로 들어감
    userVariablesMap[String, (String, String)]N사용자 변수 정보가 담긴 값
    userVariables.valueString or LongY사용자 변수에 담긴 값(텍스트, 숫자)
    userVariables.typeStringY사용자 변수의 타입(TEXT, NUMBER, JSON)

    응답 형식

    {
      "data": [
        {
          "variableName": "변수명에 해당하는 부분입니다",
          "value": "variableName에 해당하는 변수를 어떤 값으로 치환할지를 결정합니다"
        }
      ],
      "userVariable": [
        {
          "name": "사용자 변수 이름입니다",
          "value": "사용자 변수에 저장할 값입니다",
          "type": "사용자 변수의 타입입니다",
          "action": "동작을 지정합니다",
          "valueType": "저장할 값의 타입입니다"
        },
     {
        "name": "text",
        "value": "olive",
        "type": "TEXT",
        "action": "EQ",
        "valueType": "TEXT"
      },
      {
        "name": "number",
        "value": 10,
        "type": "NUMBER",
        "action": "ADD",
        "valueType": "NUMBER"
      },
      {
        "name": "date.year",
        "value": 2020,
        "type": "JSON",
        "action": "EQ",
        "valueType": "NUMBER"
      },
      {
          "name": "date.month",
        "value": 6,
        "type": "JSON",
        "action": "EQ",
        "valueType": "NUMBER"
      }
      ]
    }
    
    타입필수설명
    dataArray[Object]N액션 메소드 정보.
    data.variableNameStringY답변 안에 포함되어있는 액션 메소드 중, name.variableName과 일치하는 값을 data.value에 있는 값으로 변경함
    <예시> $2{name(arg1, arg2).variableName}
    data.valueStringYvariableName에 해당하는 변수를 어떤 값으로 바꿔줄지 결정함
    userVariableArray[Object]N사용자 변수를 변경하기 위해 사용 가능
    userVariable.nameStringY사용자 변수명. Json의 경우 값을 하나씩 수정해야 함
    .을 구분자로 하여 Json의 필드를 지정.
    userVariable.valueString or LongY변경하고자 하는 값. 텍스트나 숫자가 올 수 있음.
    userVariable.typeStringY변경하고자 하는 사용자 변수의 타입 명시.
    텍스트일 경우 TEXT, 숫자일 경우 NUMBER, Json일 경우 JSON을 입력
    userVariable.actionStringY동작 지정. 숫자일 경우에만 EQ, ADD, SUB가 올 수 있으며, 그 외의 경우 EQ만 가능
    - EQ: 기존 사용자 변수 값 대신 value를 넣음.
    - ADD: 기존 사용자 변수 값 + value 연산을 한 뒤 저장.
    - SUB: 기존 사용자 변수 값 - value 연산을 한 뒤 저장.
    userVariable.valueTypeStringYuserVariable.value의 타입 명시(TEXT, NUMBER 가능)

    LINE PAY

    LINE PAY 액션 메소드를 이용하면 챗봇에서 LINE PAY로 결제하는 시나리오를 구성할 수 있습니다. LINE PAY의 결제 방식은 두 종류입니다.

    • 가격 입력형: 입력된 가격으로 LINE PAY 결제를 진행합니다. 가격의 변동이 없는 상품을 결제할 때 활용하는 것을 권장합니다.
    • API 연동형: 입력된 외부 URL을 호출하여 확인된 가격으로 LINE PAY 결제를 진행합니다. 가격이 고정되어 있지 않거나, 사용자가 선택한 슬롯 정보에 따라 가격이 변동되는 경우 활용하는 것을 권장합니다.
    참고

    LINE PAY 서비스를 연동한 후에 사용해 주십시오.

    가격 입력형으로 결제

    가격 입력형으로 결제하는 액션 메소드를 생성하는 방법은 다음과 같습니다.

    1. 네이버 클라우드 플랫폼의 콘솔에서 Services > CLOVA Chatbot > Domain 메뉴를 차례대로 클릭해 주십시오.
    2. 원하는 도메인의 [빌더 실행하기] 버튼을 클릭하여 챗봇 빌더를 실행해 주십시오.
    3. 챗봇 빌더에서 액션 메소드 > [액션 메소드 생성] 버튼을 클릭해 주십시오.
    4. 유형을 LINE Pay로 선택해 주십시오.
    5. 이름을 확인해 주십시오.
      • 가격 입력형의 경우 액션 메소드의 이름을 직접 입력하지 않고, 가격 정보와 상품명을 입력하면 액션 메소드 이름이 자동 완성됨
    6. 가격 정보 필드에 결제할 가격을 입력해 주십시오.
      • LINE PAY의 기준 통화는 엔(¥)
    7. 상품명 필드에 결제할 상품의 이름을 입력해 주십시오.
      chatbot-chatbot-3-4_linepay01_ko

    API 연동형으로 결제

    API 연동형으로 결제하는 액션 메소드를 생성하는 방법은 다음과 같습니다.

    1. 네이버 클라우드 플랫폼의 콘솔에서 Services > CLOVA Chatbot > Domain 메뉴를 차례대로 클릭해 주십시오.
    2. 원하는 도메인의 [빌더 실행하기] 버튼을 클릭하여 챗봇 빌더를 실행해 주십시오.
    3. 챗봇 빌더에서 액션 메소드 > [액션 메소드 생성] 버튼을 클릭해 주십시오.
    4. 유형을 LINE Pay로 선택해 주십시오.
    5. 액션 메소드 이름을 입력해 주십시오.
    6. 가격 정보를 확인할 수 있는 외부 URL을 입력하고 [저장] 버튼을 클릭해 주십시오.

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

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

    API 연동형을 사용하는 경우, 연동할 API에서 아래 폼을 전달해 줘야 합니다.

    {
      "productName": "제품명",
      "amount": 0,
      "currency": "JPY"
    }
    

    <예시>
    chatbot-chatbot-3-4_linepay02_ko


    이 문서가 도움이 되었습니까?

    What's Next
    Changing your password will log you out immediately. Use the new password to log back in.
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.