commandは、userまたはmanagerがチャットWYSIWYGを通じて連携を希望する開発サーバーの機能を利用できるように作られたインターフェースです。commandが呼び出されると、チャネルトークAPIサーバーはfunctionプロトコルを通じて連携を希望するサーバーへリクエストを送信します。
commandは以下のフィールドで構成されています。
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 については開発者ページで確認できます。詳細は「Authentication」をご参照ください。（→Authentication）
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 | 呼び出し元のID |
type | string | manager | required | 呼び出し元のタイプ： |
chanel
field | type | example | required | notes |
|---|---|---|---|---|
id | string | 1432 | true | コマンドが呼び出されたチャネルのID |
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 | アプリID |
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 | 自動補完がトリガーされたチャットルームID、タイプ |
input | array（後述） | true | 入力されたパラメータリスト |
chat
field | type | required | notes |
|---|---|---|---|
type | string | true | enum-groupChat,userChat,directChat |
id | string | true | チャットルームID |
input
field | type | required | notes |
|---|---|---|---|
name | string | true | paramDefinitionに記入したパラメータ名 |
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と一致する必要がある。 |