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.
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.
There are two ways to send data to the webhook URL:
payload
parameter in 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 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!"}
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 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:
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.
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
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 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.
Slash commands can be customized in Integration. You can access Integration by clicking on your Profile Photo at the top right corner.
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.
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.
Ticking the Hide from the bot list option will prevent users from viewing and adding this bot from the bot list.
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
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.
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"}]}]}
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!"}
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
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
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
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