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",
"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
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 | notes |
---|---|---|---|---|
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
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
field | type | example | required | notes |
---|---|---|---|---|
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 | notes |
---|---|---|---|---|
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
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.
field | type | required | notes |
---|---|---|---|
type | string | true | Fixed as 'wam' |
appId | string | true | the app ID |
clientId | string | true | the client 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
{
...
"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. method
in the table below means themethod
offunction
field | value | notes |
---|---|---|
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
},
]
}
field | type | required | notes |
---|---|---|---|
chat | object ( 후술 ) | true | 자동완성이 트리거된 채팅방 아이디, 타입 |
input | array ( 후술) | true | 입력된 파라미터 목록 |
chat
field | type | required | notes |
---|---|---|---|
type | string | true | enum - groupChat, userChat, directChat |
id | string | true | 채팅방 아이디 |
input
field | type | required | notes |
---|---|---|---|
name | string | true | paramDefinition 에 기입한 파라미터 name |
value | 해당 parameter 의 type 과 동일 | true | 현재 입력된 값 |
focused | bool | true | 포커싱 여부. true 일 경우 현재 사용자가 입력중인 값. array 중 하나만 true 이고 나머지는 false. |
Response
Function 스펙의 result
만을 기술합니다.
{
"choices": [
{
"name": "option1"
"value": "value1"
},
{
"name": "option2"
"value": "value2"
},
]
}
field | type | required | notes |
---|---|---|---|
choices | array ( 후술 ) | true | 자동완성 결과로 내려줄 선택지 목록 |
choices
field | type | required | notes |
---|---|---|---|
name | string | true | 자동완성 선택지의 표기용 값 |
value | 해당 parameter 의 type 과 동일 | true | 선택시 자동완성될 값. 파라미터의 type 과 일치해야 함. |
Updated 2 months ago