Synology Chat で統合を使用

Synology Chat のカスタム統合の機能で、送受信される webhooks、ボット、およびスラッシュ コマンドを構成できます。右上の [プロファイル写真] アイコンをクリックして [統合] を選択し、この機能を有効化してください。

着信 Webhooks

着信 webhook は、外部ソースから Chat へとメッセージを投稿します。これは、JSON payload による一般的な HTTP リクエストを、その他のオプションの設定とともに活用しています。

メッセージの送信方法:

webhook URL にデータを送信するには、2 つの方法があります。

JSON payload には、text プロパティを含めることができます。これは、割り当てらたチャンネルに投稿されます。例:

payload={"text":"First line of message to post in the channel.\nAlso you can have a second line of message."}

リンクを追加する方法:

リンクを追加するには、直接 text にリンクを入力することができます。例:

payload={"text":"<https://www.synology.com>"}

別の例:

payload={"text":"Check this!!<https://www.synology.com|Click here> for details!"}

ファイルのアップロード方法:

着信ポストにファイルをアップロードすることもできます。ファイルをアップロードするには、JSON payload に、file_url プロパティとオプションのテキスト プロパティが含まれている必要があります。URL をダウンローし、ユーザー ファイル アップロード投稿として処理します。例:

payload={"text":"a fun image", "file_url":"http://imgur.com/xxxxx"}

注:

送信 Webhooks

送信 webhooks は、Chat メッセージでのトリガー単語をリッスンします。これらのトリガー単語は、外部 URL に関連データを送信します。送信 webhooks は、以下の 1 つまたは両方の状態が満たされた場合にのみトリガーできます。

チャンネルが示されている場合、このトリガー単語はオプションとなります。トリガー単語は、選択されているチャンネルがない場合に必須です。ただし、2 つの状況が定義されている場合は、送信 webhook は、2 つの状況が同時に満たされた場合にのみ発動します。

送信データ:

受信したメッセージがトリガーと一致する場合、POST は、割り当てられた URL に提供されます。データ フィールドを以下で説明します。

token: bot token
channel_id
channel_name
user_id
username
post_id
timestamp
text
trigger_word: which trigger word is matched

応答:

外部の対象が、Chat チャンネルにおいて応答を必要とする場合には、JSON が応答の本文で返される必要があります。サポートされているフィル度は、受信 webhook JSON と同じです。

スラッシュ コマンド

スラッシュ コマンドにより、テキスト フィールドに「/」を入力することで簡単に送信 webhooks をトリガーできます。返信はあなたにのみ見えます。そのため他のユーザーは、自分に関係のないメッセージを避けることができます。

スラッシュ コマンドの作成方法:

スラッシュ コマンドは [統合] でカスタマイズできます。右上隅のプロファイル写真をクリックすると [統合] にアクセスできます。

スラッシュ コマンドの使用方法:

チャンネルまたは会話のテキストフィールドにフォワード スラッシュ「/」を入力すると、あなたおよびあなたのチームが作成したコマンドのリストが表示されるので、あなたはそこから選択ができます。例えば、「/」を入力して、「/lunch」を選択すると、webhook は私に食事を勧めます。

ボット

ボットであなたと1対1の会話を開始し、外部ソースから送信されたメッセージを投稿し、会話のユーザーが送信したメッセージを聞くことができるます。

ユーザーがあなたのボットでアクティブな会話をすることを禁止する方法:

[ボット リストから隠す] オプションにチェックを入れると、ユーザーがボット リストからこのボットを見たり、追加を行ったりすることを停止させることができます。

発信データの送信方法:

発信 URL をボットの構成フィールドに入力すると、ユーザーがボットにメッセージを送信した時に Chat がリクエストを URL に送信します。データ フィールドには以下のように記載されます。

token: bot token
user_id
username
post_id
timestamp
text

注:

受信メッセージの送信方法:

POST request の payload パラメータを通して受信者とメッセージを割り当てることができます。例:

payload={"text":"First line of message to post in the channel.\nAlso you can have a second line of message.", "user_ids":[5] }

これは、First line of message to post in the channel.\nAlso you can have a second line of message.> が5の user_id を持つユーザーに送信されたことを意味します。

受信メッセージにメッセージを添付する方法:

ボットとの会話では、ボットはテキストとファイルを送信することができます。また、特殊なデータ (添付ファイル) とインタラクティブなオブジェクト (アクション) を添付することができます。現在、ボタンはインタラクティブなオブジェクトに対して提供されています。添付したいメッセージは payload の attachments フィールドに追加することができます。例:

attachments: array of attachment object

attachment object:{
callback_id: string[2], which refers to the string self-defined by the bot service.This will be sent to you when a user triggers an event attached with data.
text: string
actions: array of action object
}

action object:{
type:"button"
text: string
name: string
value: string
style: string, where green, grey, red, orange, blue, and teal are the feasible values
}

例:

payload={"text":"Hello World", "user_ids":[3], "attachments":
[{"callback_id":"abc", "text":"attachment", "actions":
[{"type":"button", "name":"resp", "value":"ok", "text":"OK", "style":"green"}]}]}

ユーザーがトリガーしたなデータを受信する方法:

ユーザーがインタラクティブなオブジェクトをトリガーすると、Chat はボットの発信 URL にリクエストを送信します。データ フィールドを以下で説明します。

payload = {
"actions": array of action object, which refers to the action triggered by the user
"callback_id": string, which refers to the callback_id of the attachment where the action triggered by the user is located
"post_id"
"token"
"user":{
"user_id"
"username"
}
}

ボットはリクエストを受け取った後で、JSON データに送り返して元のポストを改定できます。user_id を除き、サポートされるフォーマットは payload のものと同じです。

例:

{"text": "Got your response!"}

ボットで見ることができる会話をリストにする方法:

以下の URL にリクエストを送信できます。
[Chat URL]/webapi/entry.cgi?api=SYNO.Chat.External&method=channel_list&version=2

そして、以下のパラメータを組み込みます。
token = bot token

ボットで見ることができるユーザーをリストにする方法:

以下の URL にリクエストを送信できます。
{Chat URL}/webapi/entry.cgi?api=SYNO.Chat.External&method=user_list&version=2

そして、以下のパラメータを組み込みます。
token = bot token

ボットで見ることができるメッセージをリストにする方法:

以下の URL にリクエストを送信できます。
{Chat URL}/webapi/entry.cgi?api=SYNO.Chat.External&method=post_list&version=2

そして、以下のパラメータを組み込みます。
token = bot token
channel_id = channel_id is intended for browsing
next_count = the number of messages that comes after a post
prev_count = the number of messages that comes before a post, with 1 as the minimum
(optional)post_id = post_id is intended for browsing, the unfilled post_id refers to the newest message

ファイルのデータをダウンロードする方法:

以下の URL にリクエストを送信できます。
{Chat URL}/webapi/entry.cgi?api=SYNO.Chat.External&method=post_file_get&version=2&post_id={post id}&token="{bot token}"

そして、以下のパラメータを組み込みます。
token = bot token
post_id = post_id is intended for browsing

注: