Using Integration in Synology Chat

The custom integration features in Synology Chat enable you to configure incoming and outgoing webhooks, bots, and slash commands. Please click the Profile Photo icon on the upper-right and select Integration to enable these features.

Incoming Webhooks

An incoming webhook will post messages from external sources into Chat. It takes advantage of general HTTP requests with a JSON payload, along with other optional settings.

To send messages:

There are two ways to send data to the webhook URL:

• A JSON string as the payload parameter in a POST request.
• A JSON string as the body of a POST request.

The JSON payload can include a text property, which will be posted to the assigned channel. For example:

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

To add links:

To add a link, you can input its link directly into the text. For example:

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

Another example:

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

To upload files:

You can also upload a file in your incoming posts. To upload a file, your JSON payload must contain a file_url property and also an optional text property. We'll download your URL and treat it as a user file upload post. For example:

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

Outgoing Webhooks

Outgoing webhooks listen for trigger words in Chat messages. These trigger words will send relevant data to an external URL. Outgoing webhooks can only be triggered when one or both of the conditions below are met:

• The message is in a specific channel.
• The message begins with one of the selected trigger words.

If a channel is indicated, the trigger words are optional. Trigger words are required if no channel is selected. However, if two conditions are both defined, the outgoing webhook will only happen when two conditions are met at the same time.

Outgoing data:

When a message received matches a trigger, a POST will be delivered to the assigned URL. Data fields are described below:

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

Responding:

If the external destination wants to respond in the Chat channel, the JSON needs to be returned in the body of the response. Supported fields are the same as an incoming webhook JSON.

Slash Commands

Slash commands allow you to easily trigger outgoing webhooks by typing "/" in the text field. Replies will be only visible to you, so other users can avoid any messages that are irrelevant to them.

To create a slash command:

Slash commands can be customized in Integration. You can access Integration by clicking on your Profile Photo at the top right corner.

To use a slash command:

Type forward slash "/" in the text field of any channel or conversation, and a list of commands created by you and your teams will be displayed for you to choose from. For example, if you type "/" and select "/lunch", the webhook will recommend a meal for you.

Bots

A bot can start a one-on-one conversation with you, post messages sent from external sources, and listen to the messages sent by user in a conversation.

To disallow users from starting an active conversation with your bots:

Ticking the Hide from the bot list option will prevent users from viewing and adding this bot from the bot list.

To send outgoing data:

After you have entered an outgoing URL into the bot configuration field, Chat will send a request to the URL when a user sends a message to the bot. Data fields are described below:

token: bot token
user_id
username
post_id
timestamp
text

To send incoming messages:

You can assign the receivers and messages through the payload parameter in a POST request. For example:

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

This means that the message First line of message to post in the channel.\nAlso you can have a second line of message.> was sent to the user with user_id of 5.

To attach messages to incoming messages:

In a conversation with a bot, the bot can send texts and files and can also attach special data (attachment) and interactive objects (action). Currently, buttons are offered for interactive objects. You can add the message you want to attach to the attachments field in the payload. For example:

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

To receive interactive data triggered by users:

Chat will send a request to the bot's outgoing URL when a user triggers an interactive object. Data fields are described below:

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

After a bot receives a request, it can send back the JSON data to revise the original post. Except for user_id, the supported format is the same as that of payload.

For example:

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

To list the conversations visible by a bot:

You can send a request to the following URL:
[Chat URL]/webapi/entry.cgi?api=SYNO.Chat.External&method=channel_list&version=2

and can incorporate the parameter below:
token = bot token

To list the users visible by a bot:

You can send a request to the following URL:
{Chat URL}/webapi/entry.cgi?api=SYNO.Chat.External&method=user_list&version=2

and can incorporate the parameter below:
token = bot token

To list the messages visible by a bot

You can send a request to the following URL:
{Chat URL}/webapi/entry.cgi?api=SYNO.Chat.External&method=post_list&version=2

and can incorporate the parameters below:
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

To download the data of files:

You can send a request to the following URL:
{Chat URL}/webapi/entry.cgi?api=SYNO.Chat.External&method=post_file_get&version=2&post_id={post id}&token="{bot token}"

and can incorporate the parameters below:
token = bot token
post_id = post_id is intended for browsing