Utilisation de l'intégration dans Synology Chat

Les fonctionnalités d'intégration personnalisée dans Synology Chat vous permettent de configurer les webhooks entrants et sortants, les bots et les commandes slash. Cliquez sur l'icône Photo du profil, en haut à droite, et sélectionnez Intégration pour activer ces fonctionnalités.

Webhooks entrants

Un webhook entrant publie les messages à partir de sources externes dans Chat. Il bénéficie des demandes générales HTTP avec une charge utile JSON, ainsi que d'autres paramètres optionnels.

Pour envoyer des messages :

Il existe deux manières d'envoyer des données à l'URL du webhook :

• Une chaîne JSON en tant que paramètre payload (charge utile) dans une POST request.
• Une chaîne JSON en tant que corps d'une POST request.

La charge utile JSON peut comprendre une propriété text, qui sera publiée sur la chaîne assignée. Par exemple :

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

Pour ajouter des liens :

Pour ajouter un lien, vous pouvez le saisir directement dans la propriété text. Par exemple :

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

Autre exemple :

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

Pour charger des fichiers :

Vous pouvez également charger un fichier dans vos billets entrants. Pour charger un fichier, votre charge utile JSON doit comporter une propriété file_url et également une propriété text optionnelle. Nous allons télécharger votre URL et la traiter en tant que billet de chargement de fichier utilisateur. Par exemple :

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

Webhooks sortants

Les webhooks sortants sont à l'écoute de mots déclencheurs dans les messages Chat. Ces mots déclencheurs envoient les données correspondantes à une URL externe. Les webhooks sortants ne peuvent être déclenchés que lorsqu'une ou les deux conditions ci-dessous sont remplies :

• Le message figure dans une chaîne spécifique.
• Le message commence par l'un des mots déclencheurs sélectionnés.

Si une chaîne est indiquée, les mots déclencheurs sont facultatifs. Les mots déclencheurs sont obligatoires si aucune chaîne n'est sélectionnée. Toutefois, si les deux conditions sont définies, le webhook sortant ne survient que lorsque les deux conditions sont remplies en même temps.

Données sortantes :

Lorsqu'un message reçu correspond à un déclencheur, un POST est envoyé à l'URL attribuée. Les champs de données sont décrits ci-dessous :

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

Réponse :

Si la destination externe souhaite répondre sur la chaîne de Chat, le JSON doit être renvoyé dans le corps de la réponse. Les champs pris en charge sont identiques à ceux du JSON du webhook entrant.

Commandes slash

Les commandes slash vous permettent de déclencher facilement des webhooks sortants en saisissant « / » dans le champ de texte. Les réponses ne sont visibles que par vous, de sorte que d'autres utilisateurs peuvent éviter les messages qui ne les concernent pas.

Pour créer une commande slash :

Vous pouvez personnaliser les commandes slash dans Intégration. Vous pouvez accéder à Intégration en cliquant sur votre photo de profil, dans le coin supérieur droit.

Pour utiliser une commande slash :

Saisissez une barre oblique « / » dans le champ de texte d'une chaîne ou d'une conversation. Une liste des commandes créées par vous ou vos équipes s'affiche alors pour vous permettre de faire votre choix. Par exemple, si vous saisissez « / » et que vous sélectionnez « /lunch », le webhook vous recommande un repas.

Bots

Un bot peut démarrer une conversation en tête-à-tête avec vous, publier des messages envoyés par des sources externes et écouter les messages envoyés par un utilisateur dans une conversation.

Pour ne plus autoriser les utilisateurs à démarrer une conversation active avec vos bots :

Si vous cochez l'option Masquer dans la liste des bots, les utilisateurs ne pourront plus voir ni ajouter ce bot dans la liste des bots.

Pour envoyer des données sortantes :

Après avoir saisi l'URL sortante dans le champ de configuration du bot, Chat envoie une demande à l'URL lorsqu'un utilisateur envoie un message au bot. Les champs de données sont décrits ci-dessous :

token: bot token
user_id
username
post_id
timestamp
text

Pour envoyer des messages entrants :

Vous pouvez affecter les destinataires et les messages via le paramètre payload dans une POST request. Par exemple :

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

Cela signifie que le message First line of message to post in the channel.\nAlso you can have a second line of message.> a été envoyé à l'utilisateur doté de l'user_id 5.

Pour joindre des messages à des messages entrants :

Dans une conversation avec un bot, celui-ci peut envoyer des textes et des fichiers et également joindre des données spéciales (pièces jointes) ainsi que des objets interactifs (action). Actuellement, des boutons sont fournis pour des objets interactifs. Vous pouvez ajouter le message que vous souhaitez joindre dans le champ des pièces jointes de charge utile. Par exemple :

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
}

Par exemple :

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

Pour recevoir des données interactives déclenchées par des utilisateurs :

Chat envoie une demande à l'URL sortante du bot lorsqu'un utilisateur déclenche un objet interactif. Les champs de données sont décrits ci-dessous :

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

Une fois que le bot a reçu une demande, il renvoie les données JSON pour examiner la publication originale. Sauf pour user_id, le format pris en charge est identique à celui de payload.

Par exemple :

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

Pour dresser la liste des conversations visibles par un bot :

Vous pouvez envoyer une demande à l'URL suivante :
[Chat URL]/webapi/entry.cgi?api=SYNO.Chat.External&method=channel_list&version=2

et vous pouvez intégrer le paramètre ci-dessous :
token = bot token

Pour dresser la liste des utilisateurs visibles par un bot :

Vous pouvez envoyer une demande à l'URL suivante :
{Chat URL}/webapi/entry.cgi?api=SYNO.Chat.External&method=user_list&version=2

et vous pouvez intégrer le paramètre ci-dessous :
token = bot token

Pour dresser la liste des messages visibles par un bot

Vous pouvez envoyer une demande à l'URL suivante :
{Chat URL}/webapi/entry.cgi?api=SYNO.Chat.External&method=post_list&version=2

et vous pouvez intégrer les paramètres ci-dessous :
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

Pour télécharger les données des fichiers :

Vous pouvez envoyer une demande à l'URL suivante :
{Chat URL}/webapi/entry.cgi?api=SYNO.Chat.External&method=post_file_get&version=2&post_id={post id}&token="{bot token}"

et vous pouvez intégrer les paramètres ci-dessous :
token = bot token
post_id = post_id is intended for browsing