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.

JSON

Command

field	type	example	required	notes
name	string	"testCommand"	true
scope	string	"desk"	true	"desk"or"front"
description	string	"test description"	false
nameDescI18nMap	map	check example above	true	each language must contain"name","description”
actionFunctionName	string	"writeMessage"	true	the function that app-store will call
autoCompleteFunctionName	string	"autoComplete"	false	the function that app-store will call when autoComplete
paramDefinitions	array	check example below	true	the parameter of function calling
enabledByDefault	bool	true	false	If this option is false,the command will not run until you change it to true.

ParamDefinition

field	type	example	required	notes
name	string	userId	true	parameter name
type	string	string	required	should be one of"string","float","int","bool”
required	bool	true	true
description	string	"사용자 ID"	false
choices	array	check example below	false	when you need static choices.
nameDescI18nMap	map	same as above	false
autoComplete	bool	true	false	The parameter could be autoComplete when this option is true.

choice

field	type	example	required
name	string	country	true
value	string	KR	true
nameDescI18nMap	map	check example above	false

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

field	type	example	required	notes
appId	string	"dfaefg123"	true	The id of the app to register the command.
commands	array	list of commands	true

cURL

Shell

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.

Shell

Request Body

field	type	example	required
method	string	"getOrders"	true
params	object	check example below	true
context	object	check example below	true

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.

field	type	example	required
chat	chat	check example below	false
input	object	check example below	true
language	string	"ko"	false

chat

field	type	example	required	notes
type	string	group	true	type could be"group","userChat","directChat"
id	string	123	true	id 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.

field	type	example	required	notes
caller	object	check example below	true
channel	object	check example below	true

caller

field	type	example	required	notes
id	string	1423	false	manager or user id
type	string	manager	required	manager,user

channel

field	type	example	required	notes
id	string	1432	true	the channel id which command worked.

Request Example

JSON

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.

field	type	required	notes
type	string	true	Fixed as'wam'
appId	string	true	the app ID
name	string	true	the WAM name
wamArgs	object	false	The data to be sent to the WAM Controller

AutoComplete of Command

Example of command register payload including autoComplete

JSON

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

field	value	notes
method	{autoCompleteFunctionName in the registered command}	autoComplete request for command sent to the app server.

Request

Only includes params for Function specification.

JSON

field	type	required	notes
chat	object	true	chat id,type that triggered autoComplete
input	array	true	the list of input params

chat

field	type	required	notes
type	string	true	enum-groupChat,userChat,directChat
id	string	true	id of chat

input

field	type	required	notes
name	string	true	parameter name written in paramDefinition
value	same as parameter type	true	The value currently entered
focused	bool	true	If true,the value currently being entered by user.Only one of the arrays must be true and the rest must be false

Response

Only includes params for Function specification.

JSON

field	type	required	notes
choices	array	true	List of choices for autocomplete results

choices

field	type	required	notes
name	string	true	Indication value of the autocomplete option
value	same as parameter type	true	Value to be autocomplete when selected;must match the type of parameter