Command

커맨드란 무엇인가

command는 user 혹은 manager가 채팅 위즈윅을 통해 연동을 원하시는 개발 서버의 기능을 이용할 수 있도록 만들어진 인터페이스입니다. command 가 호출되면, 채널톡 API 서버는function 프로토콜을 통해 연동을 원하시는 서버로 요청을 전송하게 됩니다.

커맨드 등록방법

{
	"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

요청하기전 issueToken 을 통해 발급된 x-access-token 이 필요합니다. 커맨드 등록을 위한 issueToken 시에는 channelId 를 기입하지 않으셔야 한다는 점에 유의해주세요. secret 필드를 통해 발급하신 app-token 을 이용해 요청해 주셔야 합니다. appId 의 경우 개발자 페이지에서 확인하실 수 있습니다. 자세한 내용은 [인증 및 권한] 탭을 참조해 주세요.

PUT https://app-store-api.channel.io/general/v1/native/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 를 호출하게 되면 개발하신 서버의 functionEndpoint url 을 통해 요청이 전송됩니다. 개발하시는 서버에서 해당 요청을 스펙에 맞게 핸들링하고 반환하셔야 합니다. 요청과 응답 스펙은 아래와 같습니다. functionEndpoint 등록은 이 문서를 참고해주세요.

Request Body

호출되는 function 의 method 는 커맨드 등록시 actionFunctionName 을 통해 지정하실 수 있습니다

command 의 name 이 아닌 actionFunctionName 을 method 로 하여 요청을 핸들링해야 한다는 점을 유의해 주세요.

Params

호출자 정보를 제외한 커맨드 호출 정보를 담고 있습니다.

chat

input

input은 유저/매니저가 커맨드 실행에 입력한 파라미터 값입니다. 커맨드 등록 시 ParamDefinition에 매핑되는 값으로 이해하시면 됩니다. 키-값 형태의 맵으로 제공되며, ParamDefinition 에 따라 복수개의 키-값 쌍이 존재할 수 있습니다.

Context

커맨드를 누가 호출헀는지에 대한 정보를 담고 있습니다.

caller

chanel

Request Example

PUT {등록된 functionEndpoint}

{
	"method" : "some_function_name",
	"params" : {
		"chat" : {
			"id" : "{chat_id}",
			"type" : "{groupChat 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}"
		}
	}
}

Response Body

command 의 응답 스펙은 function 프로토콜 위에 구현되어 있습니다. 따라서 성공 여부에 따라 error 또는 result 중 하나를 반환해야 합니다. error 스펙은 Function 문서를 참조해 주세요. command 의 성공 응답으로 result 를 반환하는 스펙은 아래 [WAM 을 활용한 Command] 부분을 참조해 주시면 됩니다.

WAM을 활용한 Command

WAM(Web Application Module)을 활용하는 command인 경우 result 아래의 응답값을 아래와 같이 보내야 합니다. type이 wam인 응답인 경우, 클라이언트에서 WAM Controller를 호출하고 응답으로 명시한 WAM을 표시합니다.

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