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",
	"scoope" : "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

fieldtypeexamplerequirednotes
namestring"testCommand"true
scopestring"desk"true"desk" or "front"
descriptionstring"test description"false
nameDescI18nMapmapcheck example abovetrueeach language must contain "name", "description”
actionFunctionNamestring"writeMessage"truethe function that app-store will call
autoCompleteFunctionNamestring"autoComplete"falsethe function that app-store will call when autoComplete
paramDefinitionsarraycheck example belowtruethe parameter of function calling
enabledByDefaultbooltruefalseIf this option is false, the command will not run until you change it to true.

ParamDefinition

fieldtypeexamplerequirednotes
namestringuserIdtrueparameter name
typestringstringrequiredshould be one of "string", "float", "int", "bool”
requiredbooltruetrue
descriptionstring"사용자 ID"false
choicesarraycheck example belowfalsewhen you need static choices.
nameDescI18nMapmapsame as abovefalse
autoCompletebooltruefalseThe parameter could be autoComplete when this option is true.

choice

fieldtypeexamplerequirednotes
namestringcountrytrue
valuestringKRtrue
nameDescI18nMapmapcheck example abovefalse


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

fieldtypeexamplerequirednotes
appIdstring"dfaefg123"trueThe id of the app to register the command.
commandsarraylist of commandstrue

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

fieldtypeexamplerequirednotes
methodstring"getOrders"true
paramsobjectcheck example belowtrue
contextobjectcheck example belowtrue

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.

fieldtypeexamplerequirednotes
chatchatcheck example belowfalse
inputobjectcheck example belowtrue
languagestring"ko"false

chat

fieldtypeexamplerequirednotes
typestringgrouptruetype could be "group", "userChat", "directChat"
idstring123trueid of 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.

fieldtypeexamplerequirednotes
callerobjectcheck example belowtrue
channelobjectcheck example belowtrue

caller

fieldtypeexamplerequirednotes
idstring1423falsemanager or user id
typestringmanagerrequiredmanager, user

channel

fieldtypeexamplerequirednotes
idstring1432truethe channel id which command worked.

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.

fieldtyperequirednotes
typestringtrueFixed as 'wam'
appIdstringtruethe app ID
clientIdstringtruethe client ID
namestringtruethe WAM name
wamArgsobjectfalseThe data to be sent to the WAM Controller


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
fieldvaluenotes
method{autoCompleteFunctionName in the registered command}autoComplete request for command sent to the app server.

Request

Function 스펙의 params 만을 기술합니다.

{ "chat": { "type": "userChat" "id": "userChat-123" }, "input": [ { "name": "param1" "value": "val" "focused": false }, { "name": "param2" "value": "val2" "focused": true }, ] }
fieldtyperequirednotes
chatobject ( 후술 )true자동완성이 트리거된 채팅방 아이디, 타입
inputarray ( 후술)true입력된 파라미터 목록

chat

fieldtyperequirednotes
typestringtrueenum - groupChat, userChat, directChat
idstringtrue채팅방 아이디

input

fieldtyperequirednotes
namestringtrueparamDefinition 에 기입한 파라미터 name
value해당 parameter 의 type 과 동일true현재 입력된 값
focusedbooltrue포커싱 여부. true 일 경우 현재 사용자가 입력중인 값. array 중 하나만 true 이고 나머지는 false.

Response

Function 스펙의 result 만을 기술합니다.

{ "choices": [ { "name": "option1" "value": "value1" }, { "name": "option2" "value": "value2" }, ... ] }
fieldtyperequirednotes
choicesarray ( 후술 )true자동완성 결과로 내려줄 선택지 목록

choices

fieldtyperequirednotes
namestringtrue자동완성 선택지의 표기용 값
value해당 parameter 의 type 과 동일true선택시 자동완성될 값. 파라미터의 type 과 일치해야 함.