Command

커맨드란 무엇인가

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

ParamDefinition

choice

Register API

Request

요청하기전, channelId 없이 "issueToken" native function을 통해 발급된 "x-access-token"이 필요합니다.

PUT https://app-store-api.channel.io/general/v1/natvie/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",
        "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

method는 command를 통해서 호출하는 함수를 의미합니다.
이는 command 등록시에 함께 등록하는 actionFunctionName과 같습니다.

예를 들어, getOrder라는 command를 등록할 때,
actionFunctionName으로 getOrderById 를 등록했다면,
getOrder 커맨드를 호출할 때, method로 getOrderById 가게 됩니다.

Params

params는 해당 커맨드를 어떤 채팅 방에 대해 실행하고, 어떤 파라미터로 실행하고, 어떤 언어에 대해 실행하는 지에 대한 정보를 담고 있습니다.

chat

input
input은 command 실행 시에 app-server로 전달하는 parameter 정보입니다.
map으로 이루어져있으며, key는 command 등록할 때 사용된 param_definition의 name,
value는 해당 command실행시에 입력된 param의 value입니다.

Context

context는 누가 요청했는지, 요청한 사람이 manager인지 user인지를 담고 있고,
channel은 channel의 id가 무엇인지를 담고 있습니다.

caller

chanel

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": {
	        ...
        }
    }
}

AutoComplete of Command

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

autoComplete 을 포함한 커맨드 등록 페이로드의 예시

paramDefinition 에서 위와 같이 “autoComplete”: true 를 지정하는 경우 사용자가 해당 파라미터를 입력할 때 아래 자동완성 기능을 사용할 수 있습니다. 앱 서버는 자동완성 요청을 받아 선택지를 반환해야 합니다. 자동완성 기능을 사용하는 경우 autoCompleteFunctionName 을 반드시 지정해야 합니다. 요청/응답 스펙은 아래와 같습니다.

• autoComplete 을 포함해 앱 서버로 오는 모든 요청은 Function 스키마를 따라갑니다.
• 아래 표의 method 는 Function 의 method 를 의미합니다

{
	"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"
		},
		...
	]
}