Using action methods

Available in Classic and VPC

Use ActionMethod to link the external system data to a chatbot. You can use action method to call APIs, pass the analysis from the conversation with the user when calling APIs, or receive the result returned from APIs to be used for answering the user. For example, changeable data such as price, user, or weather information can be called from a database in real time to be provided as an answer.
A created action method is defined as the ${ActionMethodName} format to be used. Enter the action method you want to use in the {ActionMethodName} format when registering a conversation answer to call the action method when the answer is returned.

The following action methods are supported.

• Action method v1.0
• Action method v2.0
• LINE PAY
• Naver Pay
• Send CEK request
• Built-in action method

Action method parameters

A defined parameter format is required to send information to a backend system through action method. This is when an "entity" is used. A predefined entity is the key for mapping the user's data, and the entity must be defined and operated together in order to use action method. Predefined entities can also be used in action method.

Action method specifications by version

Action method v1.0

Before creating an action method, create domain entities to be used by the action method first. Enter the created action method in the answer field for the action method to be called when the answer is returned.
For example, if the answer is defined as "It is ${weather} degrees Celsius in Jeongja-dong," then the value of ${weather} is information returned as a response after calling the defined URL from the action method. If this value is "24," then the chatbot provides the answer of "It is 24 degrees Celsius in Jeongja-dong." Note that up to 2 inputs can be made in a single answer for action method v1.0.

Create GET action method

The following describes how to create a GET action method.

1. From the NAVER Cloud Platform console, click the Services > CLOVA Chatbot > Domain menus, in that order.
2. Click the [Run builder] button of the domain you want to run the chatbot builder.
3. From the chatbot builder, click the Action method menu.
4. Select the type as Action method v1.0 and GET. Enter the action method's name in the name field.
5. Enter the URL to call in the URL field.
   • When you enter $, the registered entity list will appear and you can add entities by selecting them from the list
   • Click the [Call echo] button to enter the test API automatically. Calling this action method will display the request sent from the chatbot engine to the external API server, which enables you to see how the request is made.
     
6. Select the value transmission option.
   • CLOVA authentication access token: The user request can be delivered by receiving the access token of a user account authenticated in CLOVA Extensions.
   • Session attributes: A specific string which is UTF-8-encoded can be included in the X-KAA-SESSION-ATTRIBUTES header and delivered.
7. Click the [Save] button.
   • The action method created can be used in the ${action method name} format when entering an answer.

Response format

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 ={}

Create JSON (POST) action method

The JSON (POST) method is identical to the GET method, but differs in that data can be included and sent in a URL call. Data is sent in the JSON format. Specific values other than entity data can be sent together.
The following describes how to create a POST action method.

1. From the NAVER Cloud Platform console, click the Services > CLOVA Chatbot > Domain menus, in that order.
2. Click the [Run builder] button of the domain you want to run the chatbot builder.
3. From the chatbot builder, click the Action method menu.
4. Select the type as Action method v1.0 and POST.
5. Enter the action method's name in the name field.
6. Enter the URL to call in the URL field.
   • When you enter $, the registered entity list will appear and you can add entities by selecting them from the list
   • Click the [Call echo] button to enter the test API automatically. Calling this action method will display the request sent from the chatbot engine to the external API server, which enables you to see how the request is made.
7. Enter the names of entities to be mapped in the JSON format in the data field.
   
8. Select the value transmission option.
   • CLOVA authentication access token: The user request can be delivered by receiving the access token of a user account authenticated in CLOVA Extensions.
   • Session Attributes: When a string is encoded and contained in the X-KAA-SESSION-ATTRIBUTES header, the value in X-KAA-SESSION-ATTRIBUTES is cached by the chatbot engine. When an action method with the Session attributes option is enabled, the string saved in cached X-KAA-SESSION-ATTRIBUTES is delivered with it.
9. Click the [Save] button.
   • The action method created can be used in the ${action method name} format when entering an answer.

Request format

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

Action method v2.0

How action method v2.0 differs from action method v1.0 is that it can receive multiple values with a single call.
For example, if an answer is defined as "The remaining point balance of ${membership.name} is ${membership.point} points," then the values of ${membership.name} and ${membership.point} are the values of variableName returned as a response after calling the defined URL. If the value of name is Gildong Hong, and the value of point is 1000, then the chatbot provides the answer "The remaining point balance of Gildong Hong is 1,000 points."

The following describes how to create a POST action method v2.0.

1. From the NAVER Cloud Platform console, click the Services > CLOVA Chatbot > Domain menus, in that order.
2. Click the [Run builder] button of the domain you want to run the chatbot builder.
3. From the chatbot builder, click the Action method menu.
4. Select the type as Action method 2.0 and POST.
5. Enter the action method's name in the name field.
6. Enter the URL to call in the URL field.
   • Enter $ to see the registered entity list. You can add entities by selecting them from the list.
   • Click the [Call echo] button to test the action method v2.0.
     • The method is echoed (POST is returned) if $2{action method name.method} is entered.
     • The body is echoed if $2{action method name.body} is entered.
       
7. Click the [Save] button.
   • You can use the created action method by entering $2{action method 2 name} or $2{action method 2 name.variable name} when entering answers.

Request format

{
  "actionMethod": {
    "name": "Action method name",
    "methods": [
      {
        "args": [
          "arg1",
          "age2"
        ],
        "variableName": "Variable name included in Answer 1"
      },
      {
        "variableName": "Variable name included in Answer 2"
      }
    ]
  },
  "userInfo": {
    "id": "Contains the user's ID received from messenger",
    "key": "Hashed value of the user's unique key used within the serving engine",
    "query": "Utterance entered by the user in this turn",
    "entities": {
      "Entitycode1": "Entity 1 entered by the user",
      "Entitycode2": "Entity 2 entered by the user"
    },
    "taskEntities": {
      "Entityname1": "Entity 1 filled in the task's slot",
      "Entityname2": "Entity 2 filled in the task's slot"
    },
    "userVariables": {
      "User variable name": {
        "value": "Value contained in the user variable",
        "type": "User variable type (It may be TEXT, NUMBER, or JSON)"
      }
    }
  }
}

Response format

{
  "data": [
    {
      "variableName": "Part that pertains to variable name",
      "value": "It determines to which value the variable pertaining to variableName will be substituted."
    }
  ],
  "userVariable": [
    {
      "name": "User variable name",
      "value": "Value to be saved in the user variable",
      "type": "Type of user variable",
      "action": "Specifies action",
      "valueType": "Type of value to be saved"
    },
 {
    "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 and NAVER Pay

Use the action method of LINE Pay and NAVER Pay to configure scenarios where payments are made easily with LINE Pay or NAVER Pay. The descriptions on this guide is based on LINE Pay.
There are two types of payment methods for LINE Pay and NAVER Pay.

• Price input type: Proceed with LINE Pay or NAVER Pay payments with the input price. It is recommended that you use this method for payments of products without price changes.
• API linkage type: Proceed with LINE Pay/NAVER Pay payments with the price confirmed by calling the input external URL. It is recommended that you use this method when the price is not fixed or when the price changes depending on the slot information selected by the user.

Price input type payment

The following describes how to create an action method where a price input type payment is made.

1. From the NAVER Cloud Platform console, click the Services > CLOVA Chatbot > Domain menus, in that order.
2. Click the [Run builder] button of the domain you want to run the chatbot builder.
3. From the chatbot builder, click Action method > the [Create action method] button.
4. Select the type as LINE Pay.
5. Check the name.
   • For the price input type, the action method name is automatically completed when you enter the price information and product name instead of entering the action method name directly.
6. Enter the price of the payment in the price information field.
   • LINE Pay's base currency is Japanese Yen (¥)
   • NAVER Pay's base currency is Korean Won (₩)
7. Enter the name of the product for payment in the product name field.
   

API linkage type payment

The following describes how to create an action method where an API linkage type payment is made.

1. From the NAVER Cloud Platform console, click the Services > CLOVA Chatbot > Domain menus, in that order.
2. Click the [Run builder] button of the domain you want to run the chatbot builder.
3. From the chatbot builder, click Action method > the [Create action method] button.
4. Select the type as LINE Pay.
5. Enter the action method name.
6. Enter the external URL where the price information can be checked, and click the [Save] button.

For example, if the user ordered 2 small combination pizzas, the slot information below is sent to an external URL. If the value returned as a response is "49900," the chatbot proceeds with the payment of 49,900 KRW using LINE Pay.

@Pizza: Combination pizza
@Pizza size: Small
@Pizza quantity: 2 pizzas

You must send the form below to the API to be linked when using the API linkage type.

{
  "productName": "Product name",
  "amount": 0,
  "currency": "JPY"
}

Send CEK request

It's an action method that forwards CEK requests to a specific URL. The action method for forwarding CEK requests only supports the JSON (POST) method.

1. From the NAVER Cloud Platform console, click the Services > CLOVA Chatbot > Domain menus, in that order.
2. Click the [Run builder] button of the domain you want to run the chatbot builder.
3. From the chatbot builder, click Action method > the [Create action method] button.
4. Select the type as CEK request.
5. Enter the name.
6. Enter the URL to forward the CEK requests to.
   • The request body received from CEK is forwarded.
   • Works only if the messenger is CLOVA, it won't work in the manual and automatic tests of the chatbot builder.

Built-in action method

Built-in action method is provided by CLOVA Chatbot which can utilize the chatbot's previous utterances and contexts.

The following image shows the page where the built-in action method is enabled. Click the [Edit] button of each action method to set the message to be sent in case the action method is unavailable. (Default value: I am not sure I understand. Easy explanation will help me provide a better answer.)

${`previousChatbotAnswer}

• Responses can be made by retrieving the chatbot's latest answer among the answers with a display of the marker.
• The context of the previous conversation is not followed, but the context settings of the current conversation is followed.

${`previousChatbotConPtext}

• The context settings of the previous conversation with a display of the marker are followed.
• The context of the current conversation is not followed.

${`previousChatbotAnswerContext}

• Chatbot answers and context of the previous conversation with a display of the marker can be retrieved.
• The context of the current conversation is not followed.