command는 user 혹은 manager가 채팅 위즈윅을 통해 연동을 원하시는 개발 서버의 기능을 이용할 수 있도록 만들어진 인터페이스입니다. command 가 호출되면, 채널톡 API 서버는function 프로토콜을 통해 연동을 원하시는 서버로 요청을 전송하게 됩니다.
field | type | example | required | notes |
|---|---|---|---|---|
name | string | "testCommand" | true | |
scope | string | "desk" | true |
|
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를 노출하지 않습니다. |
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 |
요청하기전 issueToken 을 통해 발급된 x-access-token 이 필요합니다. 커맨드 등록을 위한 issueToken 시에는 channelId 를 기입하지 않으셔야 한다는 점에 유의해주세요. secret 필드를 통해 발급하신 app-token 을 이용해 요청해 주셔야 합니다. appId 의 경우 개발자 페이지에서 확인하실 수 있습니다. 자세한 내용은 [인증 및 권한] 탭을 참조해 주세요.
PUT https://app-store-api.channel.io/general/v1/native/functions
field | type | example | required | notes |
|---|---|---|---|---|
appId | string | "app-123" | true | 커맨드를 등록할 app의 id |
commands | array | list of commands | true |
cURL
엔드 유저가 command 를 호출하게 되면 개발하신 서버의 functionEndpoint url 을 통해 요청이 전송됩니다. 개발하시는 서버에서 해당 요청을 스펙에 맞게 핸들링하고 반환하셔야 합니다. 요청과 응답 스펙은 아래와 같습니다. functionEndpoint 등록은 이 문서를 참고해주세요.
field | type | example | required | notes |
|---|---|---|---|---|
method | string | "getOrders" | true | |
params | object | 아래 예시 참고 | true | |
context | object | 아래 예시 참고 | true |
호출되는 function 의 method 는 커맨드 등록시 actionFunctionName 을 통해 지정하실 수 있습니다
command 의 name 이 아닌 actionFunctionName 을 method 로 하여 요청을 핸들링해야 한다는 점을 유의해 주세요.
호출자 정보를 제외한 커맨드 호출 정보를 담고 있습니다.
field | type | example | required | notes |
|---|---|---|---|---|
chat | chat | 아래 예시 참고 | true | 커맨드를 호출한 채팅방 정 |
input | object | 아래 예시 참고 | true | 호출자의 파라미터 입력값 |
language | string | "ko" | false | 호출자의 언어 |
chat
field | type | example | required | notes |
|---|---|---|---|---|
type | string | group | true | groupChat,userChat,directChat이 올 수 있습니다. |
id | string | 123 | true | chat의 id |
input
input은 유저/매니저가 커맨드 실행에 입력한 파라미터 값입니다. 커맨드 등록 시 ParamDefinition에 매핑되는 값으로 이해하시면 됩니다. 키-값 형태의 맵으로 제공되며, ParamDefinition 에 따라 복수개의 키-값 쌍이 존재할 수 있습니다.
field | type | notes |
|---|---|---|
{key} | string |
|
{value} |
| 유저/매니저가 커맨드 실행시 기입한 파라미터 |
커맨드를 누가 호출헀는지에 대한 정보를 담고 있습니다.
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 | 호출자의 아이디 |
type | string | manager | required | 호출자의 타입: |
chanel
field | type | example | required | notes |
|---|---|---|---|---|
id | string | 1432 | true | 커맨드가 호출된 채널의 아이디 |
command 의 응답 스펙은 function 프로토콜 위에 구현되어 있습니다. 따라서 성공 여부에 따라 error 또는 result 중 하나를 반환해야 합니다. error 스펙은 Function 문서를 참조해 주세요. command 의 성공 응답으로 result 를 반환하는 스펙은 아래 [WAM 을 활용한 Command] 부분을 참조해 주시면 됩니다.
field | notes |
|---|---|
error | 에러 구조체 |
result | 성공시 응답값 |
WAM(Web Application Module)을 활용하는 command인 경우 result 아래의 응답값을 아래와 같이 보내야 합니다. type이 wam인 응답인 경우, 클라이언트에서 WAM Controller를 호출하고 응답으로 명시한 WAM을 표시합니다.
field | type | required | notes |
|---|---|---|---|
type | string | true | “wam”으로 고정 |
appId | string | true | 앱 아이디 |
name | string | true | WAM 이름 |
wamArgs | object | false | WAM Controller로 넘겨줄 데이터 |
autoComplete 을 포함한 커맨드 등록 페이로드의 예시
paramDefinition 에서 위와 같이 “autoComplete”: true 를 지정하는 경우 사용자가 해당 파라미터를 입력할 때 자동완성 기능을 사용할 수 있습니다. 앱 서버는 자동완성 요청을 받아 선택지를 반환해야 합니다. 자동완성 기능을 사용하는 경우 autoCompleteFunctionName 을 반드시 지정해야 합니다. 요청/응답 스펙은 아래와 같습니다.
autoComplete을 포함해 앱 서버로 오는 모든 요청은 Function 스키마를 따라갑니다.아래 표의
method는Function의method를 의미합니다
field | value | notes |
|---|---|---|
method | {register 시에 등록한 autoCompleteFunctionName} | 앱 서버로 보내지는 커맨드의 자동완성 요청입니다 |
Request
Function 스펙의 params 만을 기술합니다.
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 만을 기술합니다.
field | type | required | notes |
|---|---|---|---|
choices | array(후술) | true | 자동완성 결과로 내려줄 선택지 목록 |
choices
field | type | required | notes |
|---|---|---|---|
name | string | true | 자동완성 선택지의 표기용 값 |
value | 해당 parameter 의 type 과 동일 | true | 선택시 자동완성될 값.파라미터의 type 과 일치해야 함. |