Convos::Controller::Events - Stream events from Convos::Core to web

  1. DESCRIPTION
  2. API
    1. Overview
    2. Methods
    3. Errors
    4. Server events
  3. METHODS
    1. start
    2. webhook
  4. SEE ALSO

DESCRIPTION

Convos::Controller::Stream is a Mojolicious::Controller which can stream events from the backend, and also act on instructions.

API

Overview

The WebSocket API is accessible from https://example.com/events. The endpoint requires an active session, meaning the WebSocket will be closed after sending back an error if an active session is not present.

Once the WebSocket is opened, it will send and receive JSON encoded messages. The messages sent to the WebSocket should contain a "method" and an "id" key.

All the code examples below are written in JavaScript, and might require that the WebSocket is already successfully set up.

Methods

ping

The "ping" method is used to keep the WebSocket open. Example:

ws.onmessage = (e) => {
  // "ts" is a high precision epoch timestamp
  // {event: "pong", ts: 1593647381.72949}
  const data = JSON.parse(e.data);
};

ws.send(JSON.stringify({method: "ping"});

send

The "send" method is used to send messages or instructions to a connection. All the input keys are echoed back, along with the response. Here are the input keys you can use:

Here is an example on how to use the "send" method:

ws.onmessage = (e) => {
  // The response will be dependent on what the action actually does
  // {event: "sent", id: 42, ...}
  const data = JSON.parse(e.data);
};

ws.send(JSON.stringify({
  method: "send",
  connection_id: "irc-whatever",
  conversation_id: "#conversation_name",
  id: 42,
  message: "some message"
});

Errors

Any invalid input or error while trying to handle the instructions will result in an error structure like this:

{
  // Required
  event: "sent", # handshake, sent, ...
  errors: [
    {message: "some error", path: "/"}
  ],

  // If present in input
  connection_id: "irc-whatever",
  id: 42,
  message: "some message",
}

The "path" inside the error element might point to which part was actually invalid. Example:

{message: "Missing connection ID.", path: "/connection_id"}

Server events

A server generated event for a given user will be be passed over the WebSocket.

Messages

A message sent in a channel, private conversation or generated by the server will result in a "messsage" event. Example:

{
  connection_id: "irc-whatever",
  conversation_id: "superwoman",
  from: "Superwoman",
  highlight: false,
  messsage: "Some message",
  ts: 1593647381.72949,
  type: "private",
}

Details:

State changes

A state change is triggered when the connection, the user or another participant changes state. It can be everything from when disconnected, nick changes or join events. Example structure:

{
  connection_id: "irc-whatever",
  conversation_id: "#conversation_name"
  nick: "Superwoman",
  type: "join",
}

Details:

METHODS

start

Will push Convos::Core::User and Convos::Core::Connection events as JSON objects over a WebSocket connection and receive messages from the frontend.

webhook

See https://convos.chat/api.html#op-post--webhook

SEE ALSO

Convos: