How do I configure webhooks and slash commands in Synology Chat?

How do I configure webhooks and slash commands in Synology Chat?

Purpose

When using Synology Chat, incoming and outgoing webhooks can be configured to facilitate integration and communication with multiple services, such as chatbots or RSS feeds. This article will guide you through the process for configuring webhooks and slash commands.

Resolution

Webhook integration

Two types of webhooks can be used to integrate and communicate with external sources. To start using webhook integration in Chat, go to User Profile > Integration.

Configure incoming webhooks

A webhook contains a payload formatted as JSON.

  1. To create a message like the one shown above, build a JSON payload, indicated as follows:
  2. {"text": "This is a test"}
  3. Place the JSON string after the payload parameter, and use application/x-www-form-urlencoded to send data to the webhook URL. For example:
  4. POST https://DS_IP/webapi/entry.cgi?api=SYNO.Chat.External&XXXXX Content-Type: application/x-www-form-urlencoded payload=%7B%22text%22%3A%22This%20is%20a%20test.%22%7D
  5. Below is an example for CURL:
  6. curl -X POST \ --data-urlencode 'payload={"text": "This is a test"}' \ https://DS_IP/webapi/entry.cgi?api=SYNO.Chat.External&XXXXX

To add links:

To add a link, you can simply insert the link into the text. For example:

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

or

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

To upload files:

Files can be uploaded to Chat via incoming webhooks.

  • To upload a file, your JSON payload must contain a file_url and also an optional text property. For example:
  • payload={"text": "a fun image", "file_url": "http://imgur.com/xxxxx"}
  • The file will be downloaded from the file_url and will then be uploaded to Chat.1

Configure outgoing webhooks

Outgoing webhooks allow you to receive messages from Chat by sending an HTTP POST request to your assigned URL when a message matches the defined trigger words and conditions.

Trigger words and conditions:

  • Outgoing webhooks can be triggered when a message matches one or both of the following conditions:
    • The message is in a specified channel.
    • The message begins with one of the defined trigger words.
  • Trigger words are optional if a channel is specified. However, trigger words are required if no channel is specified. If both of the aforementioned conditions are specified, outgoing webhooks will be sent off only when the message matches both conditions.2

Outgoing data:

  1. When a received message matches the trigger conditions, a POST will be sent to all of the specified URLs. For example:
  2. token: bot token channel_id channel_name user_id username post_id: message ID timestamp: message time text: message content trigger_word: trigger words
  3. To post a response back into Chat, the JSON needs to be returned as the body of the response (supported fields are the same as an incoming webhook JSON). For example:
  4. {"text": "This is a test"}

Configure slash commands

Another way to interact with external sources or applications is through slash commands. A slash command can be executed in any channel, and is only visible to the user who issued the command.

  1. Go to User Profile > Integration > Slash Command to register a slash command integration.
  2. To build a slash command, simply type forward slash “/” in the text field and enter your command. Examples are shown in the screenshot below:
  3. When a slash command is executed, an HTTP POST request along with some of the attributes listed below will be sent to the specified URLs (the process is similar to that of outgoing webhooks):
  4. token: bot token user_id username text: message content
  5. The external source or application will decide whether or not to respond to the slash command sent from Chat. To respond to a command request, a valid JSON payload such as the one shown below should be contained in the response:
  6. {"text": "Slash command response."}
  7. The response message as shown below will only be sent to and visible by the user who issued the command.
  8. Notes:

    1. The maximum size of a file is 32 MB.
    2. When configuring outgoing webhooks, any accessible channels can be specified. If no channel is specified, all public channels will be monitored by Chat by default.
Purpose
Contents
Resolution
Webhook integration
Configure incoming webhooks
Configure outgoing webhooks
Configure slash commands