커맨드란 무엇인가
command는 user 혹은 manager가 사용할 수 있는 기능으로, function의 wrapper입니다. app-store를 통해 command를 호출하면, 앱스토어는 내부적으로 command와 연결된 function을 호출합니다. 하나의 앱에는 여러 개의 command를 등록할 수 있으며, 각각의 command는 function과 1:1로 매칭됩니다.
커맨드 등록방법
command는 다음과 같은 필드들로 구성되어 있습니다.
{
"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
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 | 각 언어 객체는 반드시 name과 description을 포함해야합니다. |
actionFunctionName | string | "writeMessage" | true | 앱스토어가 호출할 함수의 이름입니다. |
autoCompleteFunctionName | string | "autoComplete" | false | autoComplete시에 호출할 함수의 이름입니다. |
paramDefinitions | array | check example below | true | function call에 사용되는 파라미터 입니다. |
enabledByDefault | bool | true | false | 이 옵션이 꺼져있으면 command를 노출하지 않습니다. |
ParamDefinition
field | type | example | required | notes |
---|---|---|---|---|
name | string | userId | true | 파라미터 이름 |
type | string | string | required | string, float, int, bool 중에 하나여야합니다. |
required | bool | true | true | |
description | string | "사용자 ID" | false | |
choices | array | check example below | false | 정적인 선택지가 필요할 때 사용됩니다. |
nameDescI18nMap | map | same as above | false | |
autoComplete | bool | true | false | 이 값이 true라면 해당 param은 autoComplete를 사용할 수 있습니다. |
choice
field | type | example | required | notes |
---|---|---|---|---|
name | string | country | true | |
value | string | KR | true | |
nameDescI18nMap | map | check example above | false |
Register API
Request
요청하기전, channelId 없이 "issueToken" native function을 통해 발급된 "x-access-token"이 필요합니다.
PUT https://app-store-api.channel.io/general/v1/natvie/functions
field | type | example | required | notes |
---|---|---|---|---|
appId | string | "dfaefg123" | true | 커맨드를 등록할 app의 id |
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",
"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 Handling
등록된 command를 호출하게 되면 app-store에서 command와 연결된 function으로 요청을 보내게 됩니다.
이때, 앱서버에서 실행하고 싶은 로직을 function의 구현을 통해서 실행할 수 있습니다.
functionEndpoint 등록은 이 문서를 참고해주세요.
curl -X PUT \\
'{functionEndpoint}' \\ // app 등록시에 등록한 functionEndpoint
-H 'x-access-token: {x-access-token}' \\
-H 'Content-Type: application/json' \\
- d {} // body 후술
Request Body
field | type | example | required | notes |
---|---|---|---|---|
method | string | "getOrders" | true | |
params | object | 아래 예시 참고 | true | |
context | object | 아래 예시 참고 | true |
method는 command를 통해서 호출하는 함수를 의미합니다.
이는 command 등록시에 함께 등록하는 actionFunctionName과 같습니다.
예를 들어, getOrder
라는 command를 등록할 때,
actionFunctionName으로 getOrderById
를 등록했다면,
getOrder
커맨드를 호출할 때, method로 getOrderById
가게 됩니다.
Params
params는 해당 커맨드를 어떤 채팅 방에 대해 실행하고, 어떤 파라미터로 실행하고, 어떤 언어에 대해 실행하는 지에 대한 정보를 담고 있습니다.
field | type | example | required | notes |
---|---|---|---|---|
chat | chat | 아래 예시 참고 | false | |
input | object | 아래 예시 참고 | true | |
language | string | "ko" | false |
chat
field | type | example | required | notes |
---|---|---|---|---|
type | string | group | true | group, userChat, directChat이 올 수 있습니다. |
id | string | 123 | true | chat의 id |
input
input은 command 실행 시에 app-server로 전달하는 parameter 정보입니다.
map으로 이루어져있으며, key는 command 등록할 때 사용된 param_definition의 name,
value는 해당 command실행시에 입력된 param의 value입니다.
Context
context는 누가 요청했는지, 요청한 사람이 manager인지 user인지를 담고 있고,
channel은 channel의 id가 무엇인지를 담고 있습니다.
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 |
chanel
field | type | example | required | notes |
---|---|---|---|---|
id | string | 1432 | true | 커맨드가 동작할 채널의 id |
Request Example
PUT {등록된 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}"
}
}
}
WAM을 활용한 Command
WAM(Web Application Module)을 활용하는 Command인 경우 래핑하는 function의 응답 값을 아래와 같이 보내야 합니다. type이 wam인 응답인 경우, 클라이언트에서 WAM Controller를 호출하고 응답으로 명시한 WAM을 표시합니다.
{
"type": "wam",
"attributes": {
"appId": "app_id",
"clientId": "client_it",
"name": "wam_name",
"wamArgs": {
...
}
}
}
field | type | required | notes |
---|---|---|---|
type | string | true | “wam” 으로 고정 |
appId | string | true | 앱 아이디 |
clientId | string | true | 클라이언트 아이디 |
name | string | true | WAM 이름 |
wamArgs | object | false | WAM Controller로 넘겨줄 데이터 |
AutoComplete of Command
{
...
"autoCompleteFunctionName": "autoCompleteFunctionName",
"paramDefinitions" : [
{
"autoComplete": true,
"name": "parameterName",
"required": true,
"type": "string"
}
]
...
}
autoComplete 을 포함한 커맨드 등록 페이로드의 예시
paramDefinition
에서 위와 같이 “autoComplete”: true
를 지정하는 경우 사용자가 해당 파라미터를 입력할 때 아래 자동완성 기능을 사용할 수 있습니다. 앱 서버는 자동완성 요청을 받아 선택지를 반환해야 합니다. 자동완성 기능을 사용하는 경우 autoCompleteFunctionName
을 반드시 지정해야 합니다. 요청/응답 스펙은 아래와 같습니다.
autoComplete
을 포함해 앱 서버로 오는 모든 요청은 Function 스키마를 따라갑니다.- 아래 표의
method
는Function
의method
를 의미합니다
field | value | notes |
---|---|---|
method | {register 시에 등록한 autoCompleteFunctionName} | 앱 서버로 보내지는 커맨드의 자동완성 요청입니다 |
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 과 일치해야 함. |