Использование интеграции в Synology Chat

Функции пользовательской интеграции в Synology Chat позволяют настраивать входящие и исходящие сообщения Webhook, боты и команды с косой чертой. Нажмите значок Фотография профиля в правом верхнем углу экрана и выберите Интеграция, чтобы включить эти функции.

Входящие сообщения Webhook

Поддержка входящих сообщений Webhook позволяет публиковать сообщения из внешних источников в Chat. Данная функция использует общие запросы HTTP с полезной нагрузкой JSON, а также другие дополнительные параметры.

Отправка сообщений

Существует два способа отправки данных на URL-адрес Webhook:

Полезная нагрузка JSON может содержать свойство text, которое будет опубликовано в назначенном канале. Например:

payload={"text": "Первая строка сообщения, публикуемого на канале.\nТакже можно добавить вторую строку сообщения."}

Добавление ссылок

Чтобы добавить ссылку, можно ввести ее непосредственно в тексте. Например:

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

Другой пример:

payload={"text": "Посмотрите!! <https://www.synology.com|Нажмите здесь> и узнайте больше!"}

Загрузка файлов

Можно также загрузить файл во входящие сообщения. Чтобы загрузить файл, полезная нагрузка JSON должна содержать свойство file_url, а также дополнительное свойство text. Будет выполнено скачивание URL-адреса в качестве сообщения, содержащего загруженный файл пользователя. Например:

payload={"text": "забавная картинка", "file_url": "http://imgur.com/xxxxx"}

Примечание.

Исходящие сообщения Webhook

Исходящие сообщения Webhook улавливают слова запуска в сообщениях Chat. Эти слова запуска отправляют соответствующие данные на внешний URL-адрес. Исходящие сообщения Webhook запускаются только при соблюдении одного или двух следующих условий:

Если канал указан, то слова запуска являются дополнительным условием. Слова запуска являются обязательным условием, если канал не выбран. Однако если соблюдаются оба условия, то исходящее сообщение Webhook запускается только при их одновременном соблюдении.

Исходящие данные

Если полученное сообщение соответствует триггеру, 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 необходимо вернуть в основном тексте ответа. Поддерживаемые поля соответствуют JSON входящего сообщения Webhook.

Команды с косой чертой

Команды с косой чертой позволяют запускать исходящие сообщения webhook. Для этого достаточно ввести символ «/» в текстовом поле. Ответы будут видны только вам, и другие пользователи не будут получать ненужные сообщения.

Создание команды с косой чертой

Команды с косой чертой можно настроить в разделе Интеграция. Чтобы открыть раздел Интеграция, нажмите вашу фотографию профиля в правом верхнем углу.

Использование команды с косой чертой

Введите косую черту «/» в текстовом поле любого канала или разговора. Появится список команд, созданных вами и вашими рабочими группами. Например, если ввести символ «/» и выбрать команду /lunch (обед), webhook порекомендует еду.

Боты

Бот может начать с вами разговор один на один, разместить сообщения, отправленные с внешних источников, и прослушать сообщения, отправленные пользователем в разговоре.

Запрет другим пользователям начинать разговор с вашими ботами

Установите флажок Скрыть в списке ботов, чтобы пользователи не видели и не добавляли этот бот из списка ботов.

Отправка исходящих данных

После ввода исходящего URL-адреса в поле конфигурации бота Chat отправит запрос по URL-адресу, когда пользователь отправит сообщение боту. Поля данных рассмотрены ниже.

token: bot token
user_id
username
post_id
timestamp
text

Примечание.

Отправка входящих сообщений

Вы можете назначить получателей и сообщения с помощью параметра полезной нагрузки в запросе POST. Например:

payload={"text": "Первая строка сообщения, публикуемого на канале.\nТакже можно добавить вторую строку сообщения.", "user_ids": [5] }

Это означает, что сообщениеFirst line of message to post in the channel.\nAlso you can have a second line of message.>было отправлено пользователю с user_id — 5.

Прикрепление сообщений к входящим сообщениям

В разговоре с ботом бот может отправлять тексты и файлы, а также прикладывать определенные данные (вложения) и интерактивные объекты (действия). В настоящий момент для интерактивных объектов используются кнопки. Вы можете добавить сообщение, которое хотите прикрепить к полю вложений, в полезной нагрузке. Например:

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 обратно для исправления исходных данных POST. Исключением являются случаи, когда поддерживаемый форматuser_id, совпадает с форматом данного элемента в полезной нагрузке.

Например:

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

Примечание.