Command

What is Command

Command is a function that can be used by user or manager and is also a wrapper of function. When command is called through the App Store, the App Store calls function internally registered in the command. You could register multiple commands in one app, each of which matches the function 1:1.

How to Register a Command

The command consists of the following fields.

{
	"name" : "commandName",
	"scope" : "desk",
	"description": "this is test command",
	"nameDescI18nMap": {
			"en": {
				"description": "test command en",
				"name": "test"
			},
			"ko": {
				"description": "테스트 커맨드",
				"name": "테스트"
			}
		},
	"actionFunctionName": "testFunction",
	"autoCompleteFunctionName": "autoCompleteFunctionName",
	"paramDefinitions" : [
		{
			"autoComplete": true,
			"name": "parameterName",
			"nameDescI18nMap": {
				"en": {
					"name": "parameterEn"
				},
				"ko": {
					"name": "한국어파라미터"
				}
			},
			"required": false,
			"type": "string"
		}
	],
	"enabledByDefault": true,
  "alfMode": "disable",
}

Command

ParamDefinition

choice

Register API

Request

Before request, you must have 'x-access-token" that issued by native function without channelId.

PUT https://app-store-api.channel.io/general/v1/native/functions

cURL

curl -X PUT \\
'<https://app-store-api.channel.io/general/v1/native/functions>' \\
-H 'x-access-token: {x-access-token}' \\
-H 'Content-Type: application/json' \\
-d '{
  "method": "registerCommands",
  "params": {
    "appId": "{appID}",
    "commands": [
      {
        "name": "commandName",
        "alfMode": "disable",
        "scope": "desk",
        "description": "this is test command",
        "nameDescI18nMap": {
          "en": {
            "description": "test command en",
            "name": "test"
          },
          "ko": {
            "description": "테스트 커맨드",
            "name": "테스트"
          }
        },
        "actionFunctionName": "testFunction",
        "autoCompleteFunctionName": "autoCompleteFunctionName",
        "paramDefinitions": [
          {
            "autoComplete": true,
            "name": "parameterName",
            "nameDescI18nMap": {
              "en": {
                "name": "parameterEn"
              },
              "ko": {
                "name": "한국어파라미터"
              }
            },
            "required": false,
            "type": "string"
          }
        ],
        "enabledByDefault": true
      }
    ]
  }
}'

Command Handling

When you call a registered command, the App Store sends a request to the function linked with the command.
At this time, the logic that you want to run on the App Server can be executed through the implementation of function.

Please check this document for registering functionEndpoint.

curl -X PUT \\
'{functionEndpoint}' \\ // registered at the time of app registration.
-H 'x-access-token: {x-access-token}' \\
-H 'Content-Type: application/json' \\
- d {} // check below example.

Request Body

Method means the name of the function to be invoked through the command. This is the same as the actionFunctionName that you register with at the time of command registration.

For example, when you register a Command called getOrder, If you registered getOrderById as actionFunctionName,

When calling getOrder to the App Server, method would be getOrderById.

Params

Params contains information about the chat where the command is executed, what parameters, and what language it is exected for.

chat

input

Input is information of parameter that is delivered to the App Server at the time of command execution. input is map type, key would be the name of param_definition when registering the command, value would be the input of command param.

Context

Context contains who requestd it and whether the person requested is manager or user, channel contains what tie id of the channel is.

caller

channel

Request Example

PUT {registered functionEndpoint}

{
	"method" : "some_function_name",
	"params" : {
		"chat" : {
			"id" : "{chat_id}",
			"type" : "{group or userChat or directChat}"
		},
		"input" : {
			"param_name" : "param_value"
		},
		"language": "ko"
	},
	"context" : {
		"caller" : {
			"id" : "{manager_or_user_id}",
			"type": "manager"
		},
		"channel" : {
			"id" : "{some_channel_id}"
		}
	}
}

Command with WAM

Function response of a command using a WAM(Web Application Module) should be as shown in the example below. if the value of type is wam, the App Store clients will invoke WAM Controller, invoke WAM controller from the client and display the WAM specified in response.

AutoComplete of Command

Example of command register payload including autoComplete

	{
	  ...
		"autoCompleteFunctionName": "{autoCompleteFunctionName}",
		"paramDefinitions" : [
			{
				"autoComplete": true,
				"name": "parameterName",
				"required": true,
				"type": "string"
			}
		]
		...
	}

Example of command register payload including autoComplete

If autoComplete: true is set in paramDefinition as above, the autoComplete function can be used when entering parameter values. The App Server must receive an autoComplete request and return choices. If you are using the autoCompleteFunctionName must be specified. Request/response specifications are as follows.

• Including autoComplete, every request to the App Server is as same as Function Schema.
• methodin the table below means the method of function

{
	"chat": {
	  "type": "userChat"
	  "id": "userChat-123"
 },
 "input": [
 		{
	    "name": "param1"
	    "value": "val"
			"focused": false
		},
		{
		  "name": "param2"
			"value": "val2"
		  "focused": true
		},
 ]
}

{
	"choices": [
		{
			"name": "option1"
			"value": "value1"
		},
		{
			"name": "option2"
			"value": "value2"
		},
		...
	]
}