Action method

Available in Classic and VPC

To integrate external system data into the chatbot, use the Action Method (ActionMethod). By using Action Methods, you can call APIs, pass analyzed content from the user conversation during the API call, and utilize the returned results from the API to provide responses. For example, you can retrieve variable data such as price information, user information, or weather information in real time from the database and provided as a response.
The created Action Method is defined and used in the format ${ActionMethodName}. When registering a conversation response, if you enter the Action Method in the format {ActionMethodName}, you can invoke the Action Method when delivering the response.

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 parameter

To send information to the Backend System through an Action Method, you need a defined parameter format. In this case, the 'entity' is used. Predefined entities serve as keys for mapping user data, and to use Action Methods, entities must always be defined and operate together. You can use predefined entities also within Action Methods.

Specifications of each action method version

Action method V1.0

Before creating an Action Method, first create the domain entities that are used within the Action Method. When you enter the generated Action Method into the answer field, the Action Method is invoked upon response.
For example, if the answer is defined as 'The current weather in Jeongja-dong is ${weather} degrees,' the value of ${weather} is information returned from the Response after calling the URL defined in the Action Method. If the value is '24', the chatbot responds with 'The current weather in Jeongja-dong is 24 degrees.' However, Action Method V1.0 allows a maximum of 2 entries per answer.

Create action methods using the GET method.

To create action methods using the GET method:

1. In the NAVER Cloud Platform console, navigate to > Services > AI Services > CLOVA Chatbot > Domain.
2. Click [Run builder] of the domain you want to run the Chatbot Builder.
3. Click the Action method menu in the Chatbot Builder.
4. Select Action Method V1.0 and GET as the type, then enter the Action Method's name in the name field.
5. Enter the URL you want to call to the URL field.
   • When you enter $, the list of registered entities appears, and you can select and add an entity from the list.
   • When the [Call echo] button is clicked, the test API is automatically entered. When you call the Action Method, the Request sent from the chatbot engine to the external API server is displayed as-is, allowing you to check how the Request is made.
     
6. Select the value forward option.
   • Access Token for CLOVA authentication: In CLOVA Extension, you can obtain the Access Token of an certified user account and use it to forward the user's request.
   • Session Attributes: You can include a specific UTF-8 encoded strings in the X-KAA-SESSION-ATTRIBUTES header for transmission.
7. Click [Save].
   • You can utilize the generated Action Method in the answer input field in the format of ${ActionMethodName}.

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 an Action Method using the JSON (POST) method.

The JSON (POST) method is the same as the GET method, but it allows data to be included in the URL call. The format for sending data is JSON. In addition to entity data, specific values can also be transmitted together.
To create action methods using the POST method:

1. In the NAVER Cloud Platform console, navigate to > Services > AI Services > CLOVA Chatbot > Domain.
2. Click [Run builder] of the domain you want to run the Chatbot Builder.
3. Click the Action method menu in the Chatbot Builder.
4. Select the type as Action Method V1.0, POST.
5. Enter the Action Method's name in the name field.
6. Enter the URL you want to call to the URL field.
   • When you enter $, the list of registered entities appears, and you can select and add an entity from the list.
   • When the [Call echo] button is clicked, the test API is automatically entered. When you call the Action Method, the Request sent from the chatbot engine to the external API server is displayed as-is, allowing you to check how the Request is made.
7. Enter the entity name to be mapped in JSON format in the data field.
   
8. Select the value forward option.
   • Access Token for CLOVA authentication: In CLOVA Extension, you can obtain the Access Token of an certified user account and use it to forward the user's request.
   • Session Attributes: If you encode strings and store it in the X-KAA-SESSION-ATTRIBUTES header, the chatbot engine caches the value in X-KAA-SESSION-ATTRIBUTES when an Action Method is called. When you call an Action Method with the Session Attributes option enabled, the cached strings stored in X-KAA-SESSION-ATTRIBUTES is transmitted together.
9. Click [Save].
   • You can utilize the generated Action Method in the answer input field in the format of ${ActionMethodName}.

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

The difference between Action Method V2.0 and Action Method V1.0 is that V2.0 can receive multiple values in a single call.
For example, if the answer field is defined as '${membership.name} customer's remaining points are ${membership.point}.', then the values of ${membership.name} and ${membership.point} are the 'value' of the variableName returned in the Response after calling the defined URL. If the value of name is 'Gil-dong Hong' and the value of point is '1000', then the chatbot responds: 'Gil-dong Hong customer's remaining points are 1000 points.'

To create Action Method V2.0 using the POST method:

1. In the NAVER Cloud Platform console, navigate to > Services > AI Services > CLOVA Chatbot > Domain.
2. Click [Run builder] of the domain you want to run the Chatbot Builder.
3. Click the Action method menu in the Chatbot Builder.
4. Select the type as Action Method 2.0, POST.
5. Enter the Action Method's name in the name field.
6. Enter the URL you want to call to the URL field.
   • When you enter $, the list of registered entities appears, and you can select and add an entity.
   • To test Action method V2.0, click [Call echo].
     • When you enter $2{ActionMethodName.method}, the method is echoed (POST is returned).
     • When you enter $2{ActionMethodName.body}, the body is echoed.
       
7. Click [Save].
   • You can utilize the created Action Method in the answer input by entering it in the format $2{ActionMethod2Name} or $2{ActionMethod2Name.VariableName}.

Request format

{
  "actionMethod": {
    "name": "the action method's name",
    "methods": [
      {
        "args": [
          "arg1",
          "age2"
        ],
        "variableName": "the name of a variable that the answer includes1"
      },
      {
        "variableName": "the name of a variable that the answer includes2"
      }
    ]
  },
  "userInfo": {
    "id": "The user's ID received from the messenger is contained",
    "key": "A hashed value of the user's unique key used inside the serving engine",
    "query": "The utterance the user entered in this turn",
    "entities": {
      "Entity code 1": "Entity 1 that the user entered",
      "Entity code 2": "Entity 2 that the user entered",
    },
    "taskEntities": {
      "Entity name 1": "Entity 1 filled in the task slot",
      "Entity name 2": "Entity 2 filled in the task slot",
    },
    "userVariables": {
      "User variable name":{
        "value": "Value held in the user variable",
        "type": "User variable type (TEXT, NUMBER, or JSON)"
      }
    }
  }
}

Response format

{
  "data": [
    {
      "variableName": "the part corresponding to the variable name",
      "value": "determines what value to substitute for the variable corresponding to variableName"
    }
  ],
  "userVariable": [
    {
      "name": "the name of the user variable",
      "value": "the value to be saved in a user variable",
      "type": "the type of a user variable",
      "action": "specifies the action",
      "valueType": "the type of a 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

By using the LINE Pay and NAVER Pay action methods, you can build a chatbot quickstart that enables payments through LINE Pay and NAVER Pay. This guide explains based on LINE Pay.
There are two types of payment methods for LINE Pay and NAVER Pay.

• Price input type: Proceed with LINE Pay and NAVER Pay payments using the entered price. It is recommended to use this when paying for products with fixed prices.
• API integration type: Call the entered external URL and proceed with LINE Pay/NAVER Pay payments using the confirmed price. It is recommended to use this when the price is not fixed or when the price varies depending on the slot information selected by the user.

Payment with price input type

To create an action for payment with the price input type:

1. In the NAVER Cloud Platform console, navigate to > Services > AI Services > CLOVA Chatbot > Domain.
2. Click [Run builder] of the domain you want to run the Chatbot Builder.
3. In the Chatbot Builder, click Action method > [Create action method].
4. Select LINE Pay as the type.
5. Check the name.
   • In the case of the price input type, you do not manually enter the action method name. Instead, when you input the price information and product name, the action method name is automatically completed.
6. Enter the payment price in the price information field.
   • The base currency of LINE Pay is Japanese Yen (¥).
   • The base currency of NAVER Pay is Korean Won (₩).
7. Enter the name of the product to be paid for in the product name field.
   

Pay with the API integration type.

To create an action method for payment with the API integration type:

1. In the NAVER Cloud Platform console, navigate to > Services > AI Services > CLOVA Chatbot > Domain.
2. Click [Run builder] of the domain you want to run the Chatbot Builder.
3. In the Chatbot Builder, click Action method > [Create action method].
4. Select LINE Pay as the type.
5. Enter the name of the action method.
6. Enter the external URL to check the price information and then click [Save].

For example, if the user orders two small combination pizzas, the following slot information is sent to the external URL. If the returned response value is "49,900," the chatbot proceeds with the payment of KRW 49,900 through LINE Pay.

@pizza: Combination pizzas
@pizza size: S size
@quantity: 2

When using the API integration type, the integrated API must provide the following form:

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

Example:

Forward CEK Request

An action method that bypasses all CEK Requests. The CEK Request forwarding action method only supports the JSON (POST) format.

1. In the NAVER Cloud Platform console, navigate to > Services > AI Services > CLOVA Chatbot > Domain.
2. Click [Run builder] of the domain you want to run the Chatbot Builder.
3. In the Chatbot Builder, click Action method > [Create action method].
4. Select CEK Request as the type.
5. Enter a name.
6. Enter the URL to which you want to forward the CEK Request.
   • The Request body delivered from CEK is forwarded.
   • It only works when the messenger is CLOVA, and does not operate in manual or automatic tests of the Chatbot Builder.

Built-in action method

Built-in action methods are provided directly by CLOVA Chatbot, which can utilize the chatbot's previous utterances and context.

In the interface below, the Built in action method is activated. If it is unable to implement an action method, you can set a message you want to forward by clicking the [Edit] button of the corresponding action button. (Default: I didn’t quite understand. If you explain it more simply, I can give a better answer.)

• ${`previousChatbotAnswer}
  • You can reload and respond with the most recent chatbot reply among those marked with a marker.
  • The context of the previous conversation is not followed, and the context settings of the current conversation are applied.
• ${`previousChatbotConPtext}
  • Follows the context settings of the previous conversation marked with a marker.
  • The context of the current conversation is not followed.
• ${`previousChatbotAnswerContext}
  • You can retrieve the chatbot reply and context from the previous conversation marked with a marker.
  • The context of the current conversation is not followed.