Chat Bots: Documentación técnica

El siguiente texto es una explicación detallada de cómo funcionan y cómo crear un Bot para los canales de Chat de Mazmo.

La publicamos a modo de referencia y guía, para aquellos y aquellas que deseen crear un programa que interactúe en los Chats. No es de ninguna manera información necesaria para le uso normal del sitio.

Cómo funciona un Chat Bot

Un Chat Bot puede crear mensajes en canales dentro de Mazmo, mediante una simple llamada HTTP POST.

A su vez, también puede "escuchar" eventos de canales (como mensajes nuevos, ingresos, partidas, bans, y reacciones). Estos eventos serán enviados a una url propia de tu Bot, mediante HTTP POST. Para cada evento, el programa puede analizar la información recibida y si así lo decide, ejecutar algún tipo de acción.

Inscripción de un Bot

El primer paso para crear un chat bot es darlo de alta, yendo a la página de Tus chat bots y seguir los pasos que indica el sistema para agregar un nombre y descripción.

Una vez hayas completado todos los pasos (la sección de hooks puede quedar pendiente a completar más adelante), el sistema te informará que se ha dado de alta el Bot, y te proveerá de una clave secreta, que necesitarás más adelante. Ten en cuenta que ésta será la única vez que se muestre la clave secreta. Si la pierdes, deberás crear una nueva.

API accesible por un Bot

Con la clave secreta, un Bot puede acceder a los siguientes endpoints mediante HTTP requests comunes:

Nota: La URL base de producción es https://production.mazmoapi.net.

• GET /chat/bots/channels

Requiere ser llamado con secret como query param, con el valor provisto al inscribir el Bot.

Devuelve una lista de objetos con las claves channelId y secret. La primera corresponde al ID de cada canal donde el Bot ha sido añadido. La segunda es una clave requerida para enviar mensajes e interactuar con dicho canal (no confundir esta clave secret asociada a la relación Bot-Canal, con la clave secret propia del Bot).

• POST /chat/channels/{channelId}/messages

Donde channelId es el ID del Canal con el que se quiere interactuar.

Requiere un body en formato JSON con la siguiente estructura: { rawContent: 'Cuerpo del mensaje' }. Requiere un header con la clave Bot-Key y el valor de la clave secret que asocia al Bot con el Canal.

Se utiliza para crear un mensaje, con el Bot como autor, en el canal indicado.

El cuerpo del mensaje en el body del request deberá ser un string que luego será tratado como markdown, con lo cual soporta menciones, emojis, hashtags, etcétera.

Hooks

Como se mencionó anteriormente, los Bots pueden ser alertados ante cada evento que suceda en un Canal. Esto se logra mediante hooks. Un hook no es más que una ruta a tu programa, que será llamada mediante un POST request cada vez que sea necesario.

Los hooks siempre reciben un body en formato JSON con dos parámetros: message y key.

key contiene la clave que asocia al Bot con el Canal, necesaria para enviar mensajes.

message contiene el payload del evento creado. La estructura de este campo depende del tipo de evento que se haya creado (mensaje, ingreso, partida...).

Ejemplo de payload de message para un evento de creación de un mensaje nuevo:

{
  channel: {
    name: String,
    description: String,
    participant: [{ userId: Number, joinedAt: Date, role: Enum }],
    avatar: String,
    privacy: Enum
  },
  author: {
    type: Enum,
    id: String|Number
  },
  type: Enum.
  payload: {
    rawContent: String,
    media: [{ filename: String }]
  },
  reactions: [{ name: String, authorIds: [Number] }]
}