Integration in Synology Chat nutzen

Mit den benutzerdefinierten Einbindungsfunktionen in Synology Chat können Sie eingehende und ausgehende Webhooks, Bots und Schrägstrich-Befehle konfigurieren. Klicken Sie auf das Symbol Profilfoto oben rechts und wählen Sie Einbindung, um diese Funktionen zu aktivieren.

Eingehende Webhooks

Ein eingehender Webhook postet Nachrichten von externen Quellen in den Chat. Er nutzt allgemeine HTTP-Anfragen mit einer JSON-Nutzlast, neben anderen optionalen Einstellungen.

Senden von Nachrichten:

Es gibt zwei Methoden, um Daten an die Webhook-URL zu senden:

• Eine JSON-Zeichenfolge als Parameter payload in einem POST Request.
• Eine JSON-Zeichenfolge als Text einem POST Request.

Die JSON-Nutzlast kann eine Eigenschaft text enthalten, die im zugewiesenen Kanal gepostet wird. Beispiel:

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

Hinzufügen von Links:

Um einen Link hinzuzufügen, können Sie den Link direkt in den text einfügen. Beispiel:

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

Ein weiteres Beispiel:

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

Dateien hochladen:

Sie können auch eine Datei in Ihre eingehenden Posts hochladen. Um eine Datei hochzuladen, muss Ihre JSON-Nutzlast eine Eigenschaft file_url enthalten, ebenso wie eine optionale Texteigenschaft. Wir werden Ihre URL herunterladen und als Upload-Post mit einer Nutzerdatei behandeln. Beispiel:

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

Ausgehende Webhooks

Ausgehende Webhooks suchen nach Auslöseworten in Chat-Nachrichten. Diese Auslöseworte senden relevante Daten an eine externe URL. Ausgehende Webhooks können nur ausgelöst werden wenn eine oder beide der folgenden Bedingungen erfüllt sind:

• Diese Nachricht befindet sich in einem spezifischen Kanal.
• Die Nachricht beginnt mit einem der gewählte Auslöseworte.

Wenn der Kanal angezeigt wird, sind die Auslöseworte optional. Auslöseworte sind erforderlich, wenn kein Kanal ausgewählt wurde. Wenn zwei Bedingungen beide definiert sind, erfolgt der ausgehende Webhook nur, wenn zwei Bedingungen gleichzeitig erfüllt sind.

Ausgehende Daten:

Wenn eine erhaltene Nachricht einem Auslöser entspricht, wird ein POST an die zugewiesene URL gesendet. Die Datenfelder sind nachfolgend beschrieben:

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

Antworten:

Wenn das externe Ziel im Chat-Kanal antworten möchte, muss die JSON im Text der Antwort zurückgesendet werden. Die unterstützten Felder sind dieselben wie bei einer eingehenden Webhook JSON.

Schrägstrich-Befehle

Mit Schrägstrich-Befehlen können Sie ganz einfach ausgehende Webhooks auslösen, indem Sie "/" in das Textfeld eingeben. Antworten sind nur für Sie sichtbar, so dass andere Benutzer Nachrichten vermeiden können, die irrelevant für sie sind.

Erstellen eines Schrägstrich-Befehls:

Schrägstrich-Befehle können unter Integration angepasst werden. Sie können auf die Integration zugreifen, indem Sie in der oberen rechten Ecke auf Ihr Profilfoto klicken.

Verwenden eines Schrägstrich-Befehls:

Geben Sie einen Schrägstrich „/“ in das Textfeld eines beliebigen Kanals oder einer Konversation ein und es wird eine Liste von Befehlen angezeigt, aus der Sie und Ihre Teams auswählen können. Wenn ich z. B. „/“ eingebe und „/lunch“ wähle, gibt mir der Webhook eine Empfehlung für eine Mahlzeit.

Bots

Ein Bot kann eine Einzelkonversation mit Ihnen beginnen, von externen Quellen gesendete Nachrichten posten und Nachrichten abhören, die vom Benutzer einer Konversation gesendet wurden.

Benutzern verbieten, eine aktive Konversation mit Ihren Bots zu beginnen:

Wenn Sie die Option Aus Bot-Liste ausblenden aktivieren, können Benutzer diesen Bot nicht aus der Bot-Liste anzeigen und hinzufügen.

Ausgehende Daten senden:

Nachdem Sie eine ausgehende URL in das Konfigurationsfeld des Bots eingegeben haben, sendet der Chat eine Anfrage an die URL, wenn ein Benutzer eine Nachricht an den Bot sendet. Die Datenfelder sind nachstehend beschrieben:

token: bot token
user_id
username
post_id
timestamp
text

Eingehende Nachrichten senden:

Sie können Empfänger und Nachrichten über den Parameter „payload“ in einem POST Request zuweisen. Beispiel:

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

Das bedeutet, dass die Nachricht First line of message to post in the channel.\nAlso you can have a second line of message.> an den Benutzer mit user_id 5 geschickt wurde.

Nachrichten an eingehende Nachrichten anhängen:

Bei einer Konversation mit einem Bot kann der Bot Texte und Dateien senden und spezielle Daten (Anhang) sowie interaktive Objekte (Aktion) anhängen. Zurzeit werden Schaltflächen für interaktive Objekte bereitgestellt. Sie können die Nachricht hinzufügen, die Sie im Feld „attachments“ in der Nutzlast anhängen möchten. Beispiel:

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
}

Beispiel:

payload={"text": "Hello World", "user_ids": [3], "attachments":
[{"callback_id": "abc", "text": "attachment", "actions":
[{"type": "button", "name": "resp", "value": "ok", "text": "OK", "style": "green"}]}]}

Interaktive Daten empfangen, die von Benutzern ausgelöst wurden:

Der Chat sendet eine Anfrage an die ausgehende URL des Bots, wenn ein Benutzer ein interaktives Objekt auslöst. Die Datenfelder sind nachfolgend beschrieben:

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

Nachdem ein Bot eine Anfrage erhält, kann er die JSON-Daten zurücksenden, um den ursprünglichen Post zu überarbeiten. Ausgenommen user_id entspricht das unterstützte Format dem von „payload“.

Beispiel:

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

Die für einen Bot sichtbaren Konversationen auflisten:

Sie können eine Anfrage an die nachfolgende URL senden:
[Chat URL]/webapi/entry.cgi?api=SYNO.Chat.External&method=channel_list&version=2

und nachstehende Parameter einfügen:
token = bot token

Die für einen Bot sichtbaren Benutzer auflisten:

Sie können eine Anfrage an die nachfolgende URL senden:
{Chat URL}/webapi/entry.cgi?api=SYNO.Chat.External&method=user_list&version=2

und nachstehende Parameter einfügen:
token = bot token

Die für einen Bot sichtbaren Nachrichten auflisten

Sie können eine Anfrage an die nachfolgende URL senden:
{Chat URL}/webapi/entry.cgi?api=SYNO.Chat.External&method=post_list&version=2

und nachstehende Parameter einfügen:
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

Dateidaten herunterladen:

Sie können eine Anfrage an die nachfolgende URL senden:
{Chat URL}/webapi/entry.cgi?api=SYNO.Chat.External&method=post_file_get&version=2&post_id={post id}&token="{bot token}"

und nachstehende Parameter einfügen:
token = bot token
post_id = post_id is intended for browsing