Uso de la integración en Synology Chat

Las funciones de integración personalizada en Synology Chat le permiten configurar webhooks entrantes y salientes, bots y comandos con barra. Haga clic en el icono Foto de perfil, en la parte superior derecha, y seleccione Integración para habilitar estas funciones.

Webhooks entrantes

Un webhook entrante publicará mensajes de fuentes externas en Chat. Se beneficia de las solicitudes generales HTTP con una carga útil de JSON, junto a otras configuraciones opcionales.

Para enviar mensajes:

Existen dos formas de enviar los datos a la URL de webhook:

• Una cadena de JSON como el parámetro payload en una POST request.
• Una cadena de JSON como el cuerpo de una POST request.

La carga útil de JSON puede incluir una propiedad text, que se publicará en el canal asignado. Por ejemplo:

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

Para añadir vínculos:

Para agregar un vínculo, puede introducir su vínculo directamente en text. Por ejemplo:

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

Otro ejemplo:

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

Para cargar archivos:

También puede cargar un archivo en sus publicaciones entrantes. Para cargar un archivo, su carga útil de JSON debe contener una propiedad file_url, así como una propiedad de texto opcional. Vamos a descargar su URL y tratarla como una publicación de carga de archivo de usuario. Por ejemplo:

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

Webhooks salientes

Los webhooks salientes escuchan palabras de activación en los mensajes de Chat. Estas palabras de activación enviarán datos importantes a una URL externa. Los webhooks salientes solo pueden activarse cuando una o ambas de las siguientes condiciones se cumplen:

• El mensaje se encuentra en un canal específico.
• El mensaje comienza con una de las palabras de activación seleccionadas.

Si un canal está indicado, las palabras de activación son opcionales. Las palabras de activación son necesarias si no hay ningún canal seleccionado. Sin embargo, si dos condiciones están definidas, el webhook saliente solo se producirá cuando dos condiciones se cumplan al mismo tiempo.

Datos salientes:

Cuando un mensaje recibido coincide con un activador, se enviará un POST a la URL asignada. Los campos de datos se describen a continuación:

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

Respuesta:

Si el destino externo quiere responder en el canal de Chat, el JSON se tiene que devolver en el cuerpo de la respuesta. Los campos compatibles son los mismos que en un webhook de JSON entrante.

Comandos con barra

Los comandos con barra le permiten activar fácilmente webhooks de salida escribiendo "/" en el campo de texto. Solo usted podrá visualizar las respuestas, por lo que el resto de usuario puede evitar los mensajes que no sean relevantes para ellos.

Para crear un comando con barra:

Los comandos con barras se pueden personalizar en Integración. Para acceder a Integración, haga clic en su Foto de perfil en la esquina superior derecha.

Para utilizar un comando con barra:

Escriba la barra invertida "/" en el campo de texto de cualquier canal o conversación y una lista de comandos creada por usted, y se mostrarán sus equipos para que elija entre ellos. Por ejemplo, si escribo "/" y selecciono "/almuerzo", el webhook le recomendará un almuerzo.

Bots

Un bot puede iniciar una conversación individual, publicar mensajes enviados desde fuentes externas y escuchar los mensajes enviados por el usuario en una conversación.

Para impedir que los usuarios inicien una conversación activa con sus bots:

Marcar la opción Ocultar de la lista de bot evitará que los usuarios puedan ver y agregar este bot desde la lista de bots.

Para enviar datos salientes:

Después de introducir una dirección URL saliente en el campo de configuración del bot, Chat enviará una solicitud a la dirección URL cuando un usuario envíe un mensaje al bot. Los campos de datos se describen a continuación:

token: bot token
user_id
username
post_id
timestamp
text

Para enviar mensajes entrantes:

Puede asignar los receptores y los mensajes mediante el parámetro de carga útil en una POST request. Por ejemplo:

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

Esto significa que el mensaje First line of message to post in the channel.\nAlso you can have a second line of message.> se ha enviado al usuario con el user_id 5.

Para adjuntar mensajes a los mensajes entrantes:

En una conversación con un bot, el bot puede enviar mensajes y archivos, así como adjuntar datos especiales (adjuntos) y objetos interactivos (acciones). Actualmente, se ofrecen botones para los objetos interactivos. Puede agregar el mensaje que desea adjuntar al campo de archivos adjuntos en la carga útil. Por ejemplo:

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
}

Por ejemplo:

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

Para recibir datos interactivos activados por los usuarios:

Chat enviará una solicitud a la dirección URL saliente del bot cuando un usuario active un objeto interactivo. Los campos de datos se describen a continuación:

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

Tras recibir una solicitud, un bot puede devolver los datos JSON para revisar la publicación original. A excepción de user_id, el formato compatible es el mismo que el de la carga útil.

Por ejemplo:

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

Para indicar las conversaciones visibles para un bot,

puede enviar una solicitud a la siguiente dirección URL:
[Chat URL]/webapi/entry.cgi?api=SYNO.Chat.External&method=channel_list&version=2

y puede incorporar el siguiente parámetro:
token = bot token

Para indicar los usuarios visibles para un bot:

puede enviar una solicitud a la siguiente dirección URL:
{Chat URL}/webapi/entry.cgi?api=SYNO.Chat.External&method=user_list&version=2

y puede incorporar el siguiente parámetro:
token = bot token

Para indicar los mensajes visibles para un bot,

puede enviar una solicitud a la siguiente dirección URL:
{Chat URL}/webapi/entry.cgi?api=SYNO.Chat.External&method=post_list&version=2

y puede incorporar los siguientes parámetros:
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

Para descargar los datos de archivos:

puede enviar una solicitud a la siguiente dirección URL:
{Chat URL}/webapi/entry.cgi?api=SYNO.Chat.External&method=post_file_get&version=2&post_id={post id}&token="{bot token}"

y puede incorporar los siguientes parámetros:
token = bot token
post_id = post_id is intended for browsing