액션 메소드

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

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

• 액션 메소드V1.0
• 액션 메소드V2.0
• LINE PAY
• Naver Pay
• CEK Request 전송
• Built in 액션 메소드

액션 메소드 파라미터

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

액션 메소드 버전별 스펙

액션 메소드 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되는지 확인 가능
     
6. 값 전송 옵션을 선택해 주십시오.
   • CLOVA 인증 Access Token: CLOVA Extension에서 인증된 사용자 계정의 Access Token을 받아 사용자 요청을 전달 가능
   • 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 ={}

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

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

1. 네이버 클라우드 플랫폼의 콘솔에서 Service > CLOVA Chatbot > Domain 메뉴를 차례대로 클릭해 주십시오.
2. 원하는 도메인의 [빌더 실행하기] 버튼을 클릭하여 챗봇 빌더를 실행해 주십시오.
3. 챗봇 빌더에서 액션 메소드 메뉴를 클릭해 주십시오.
4. 유형을 액션 메소드 V1.0, POST로 선택해 주십시오.
5. 이름 필드에 액션 메소드의 이름을 입력해 주십시오.
6. URL 필드에 호출할 URL을 입력해 주십시오.
   • $를 입력하면 등록된 엔티티 목록이 나타나고, 엔티티 목록에서 엔티티를 선택하여 추가 가능
   • [echo 호출] 버튼 클릭 시 테스트 API가 자동으로 입력됨. 해당 액션 메소드 호출 시 챗봇 엔진에서 외부 API 서버로 전달되는 Request가 그대로 표시되어, 어떤 방식으로 Request되는지 확인 가능
7. 데이터 필드에 JSON 형식을 갖추어 매핑할 엔티티 이름을 입력해 주십시오.
   
8. 값 전송 옵션을 선택해 주십시오.
   • CLOVA 인증 Access Token: CLOVA Extension에서 인증된 사용자 계정의 Access Token을 받아 사용자 요청을 전달 가능
   • 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"} 

액션 메소드 V2.0

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

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

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

응답 형식

{
  "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"
  }
  ]
}

LINE PAY와 NAVER PAY

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

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

가격 입력형으로 결제

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

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

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"
}

<예시>

CEK Request 전달

CEK Request를 전부 bypass 해주는 액션 메소드입니다. CEK Request 전달 액션 메소드는 JSON(POST) 방식만 지원합니다.

1. 네이버 클라우드 플랫폼의 콘솔에서 Service > CLOVA Chatbot > Domain 메뉴를 차례대로 클릭해 주십시오.
2. 원하는 도메인의 [빌더 실행하기] 버튼을 클릭하여 챗봇 빌더를 실행해 주십시오.
3. 챗봇 빌더에서 액션 메소드 > [액션 메소드 생성] 버튼을 클릭해 주십시오.
4. 유형을 CEK Request로 선택해 주십시오.
5. 이름을 입력해 주십시오.
6. CEK Request를 전달할 URL을 입력해 주십시오.
   • CEK에서 전달된 Request body를 전달합니다.
   • 메신저가 CLOVA인 경우에만 동작하며, 챗봇 빌더의 수동 테스트 및 자동 테스트에서는 동작하지 않습니다.

Built in 액션 메소드

Built in 액션 메소드는 CLOVA Chatbot에서 자체적으로 제공하는 액션 메소드로, 챗봇의 이전 발화 및 컨텍스트를 활용할 수 있습니다.

다음 화면은 Built in 액션 메소드가 활성화된 상태입니다. 각 액션 메소드의 [수정] 버튼을 클릭하면 해당 액션 메소드 수행이 불가할 경우 발송할 메시지를 설정할 수 있습니다. (기본값: 잘 이해하지 못했어요. 쉽게 설명해주시면 더 좋은 대답을 할 수 있어요.)

${`previousChatbotAnswer}

• 마커가 표시된 답변 중 가장 최근에 응답한 챗봇의 답변을 다시 불러와 응답할 수 있습니다.
• 이전 대화의 컨텍스트는 따르지 않으며, 현재 대화의 컨텍스트 설정을 따릅니다.

${`previousChatbotConPtext}

• 마커가 표시된 이전 대화의 컨텍스트 설정을 따릅니다.
• 현재 대화의 컨텍스트는 따르지 않습니다.

${`previousChatbotAnswerContext}

• 마커가 표시된 이전 대화의 챗봇 답변과 컨텍스트를 불러올 수 있습니다.
• 현재 대화의 컨텍스트는 따르지 않습니다.