使用 Synology Chat 整合功能

Synology Chat 中的自訂整合功能可讓您設定傳入和傳出 webhook 、機器人以及斜線指令。請按一下右上角的個人照片 並選擇整合功能來啟用這些服務。

傳入 webhook

傳入 webhook 會從外部來源張貼文章到 Chat。利用一般的 HTTP 要求及 JSON 承載資料進行張貼,並有其他選用設定可供使用。

若要傳送訊息:

傳送資料至 webhook 網址有兩種方式:

JSON 承載資料可以帶有 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 承載資料中必須含有 file_url 屬性及其他選用的文字屬性。系統將會下載網址,並且將該網址視為使用者的檔案上傳文章來處理。例如:

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

注意:

傳出 webhook

傳出 webhook 負責接聽 Chat 訊息中的觸發字。觸發字將會傳送相關資料到外部網址。符合下列所有或其中狀況時,才會觸發傳出 webhook:

如果已指定頻道,觸發字則為選用。如果未選取任何頻道,必須使用觸發字。然而,如果上述兩種狀況皆已定義,僅在兩種狀況同時符合時,才會執行傳出 webhook。

傳出資料:

當接收的訊息符合觸發字時,將會自動傳送文章至指定的網址。資料欄位的描述如下:

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 相同。

斜線指令

斜線指令讓您只要在文字欄位輸入「/」就能輕鬆的觸發傳出 webhook。就只有您看的到回覆,避免其他使用者收到對他們不相關的訊息。

若要新增斜線指令:

您可以在整合功能自訂斜線指令。按一下右上角的個人照片,即可進入整合功能

若要使用斜線指令:

在任何的頻道或對話中的文字欄位輸入「/」就會顯示所有您自訂的斜線指令,讓你選擇。例如,如果我輸入「/lunch」,webhook 將會向推薦午餐選項。

機器人

機器人能夠與使用者建立一對一的對話,在對話中張貼外部傳入的訊息並接聽使用者在該對話中送出的訊息。

若要限制使用者與您的機器人主動對話:

勾選於機器人列表隱藏選項後,使用者將無法在機器人列表中瀏覽並加入此機器人。

若要傳出資料:

當您在機器人的設定欄位填入傳出網址後,若使用者向機器人傳送訊息,Chat 便會向該網址發出請求。資料欄位描述如下:

token: bot token
user_id
username
post_id
timestamp
text

注意:

若要傳入訊息:

您可以透過在張貼文章要求中的 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.> 已傳送給 user_id 為 5 的使用者。

若要在傳入訊息附加訊息:

在與機器人的對話中,機器人除了可以發送一般文字和檔案之外,還可以讓訊息附加特殊資料 (attachment) 與互動式物件 (action)。目前互動式物件只提供按鈕。您可以在 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
}

For example:

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 便會向機器人的傳出網址發出請求。資料格式如下:

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!"}

若要列出機器人可看到的頻道:

您可以發送請求至下列網址:
[Chat URL]/webapi/entry.cgi?api=SYNO.Chat.External&method=channel_list&version=2

並帶入以下參數:
token = bot token

若要列出機器人可看到的使用者:

您可以發送請求至下列網址:
{Chat URL}/webapi/entry.cgi?api=SYNO.Chat.External&method=user_list&version=2

並帶入以下參數:
token = bot token

若要列出機器人可看到的文章:

您可以發送請求至下列網址:
{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

若要下載檔案資料:

您可以發送請求至下列網址:
{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

注意: