Subscription events

Introduction to subscription events

Chatkit sends event notifications over a variety of subscriptions that each client maintains with the service. These are referred to as user, room, and presence subscriptions.

The subscriptions are each responsible for handling different types of events:

  • User subscription: A client will only ever have at most one user subscription. The user subscripiton receives ephemeral events that are relevant to the subscribed user. For example, the user would be notified that they had been added to a room via an event sent over their user subscription.
  • Presence subscription: As with the user subscription there is only ever at most one presence subscription per client. It keeps the client updated on changes to the presence state of the users that the client shares at least one room membership with.
  • Room subscription: A client can have any number of room subscriptions. They are used to receive new messages that are added to a room.

Event format

A JSON object containing the following keys:

  • event_name: Name of event.
  • timestamp: Timestamp with time zone formatted to RFC3339.
  • data: Data relating to the specific event. Refer to individual event types for more detailed information.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "event_name": "room_updated",
  "data": {
    "room": {
      "id": "1",
      "created_by_id": "ham",
      "name": "my-cool-room",
      "created_at": "2017-03-23T11:36:42Z",
      "updated_at": "2017-03-23T11:36:42Z"
    }
  },
  "timestamp": "2017-03-23T11:36:42Z"
}

How HTTP Subscriptions work

Most users won’t need to know about these details. Read on if you are implementing your own client that supports the HTTP SUBSCRIBE method or are just interested.

We use the HTTP SUBSCRIBE method to receive a stream of events. These events are streamed into the HTTP response body. The events will be received in the order they are published and the stream will only end when the client disconnects or the server ends the connection (in normal circumstances).

Each event from the stream contains some data, in Chatkit’s case this could be a message or a user update for example. There are other event types: control messages and EOS (end of stream) messages. The format of these is described in more detail below.

Response body and event types

Events are streamed into the HTTP response body. Each event is a JSON array; the first element dictates its type. The remaining elements depend on the message type.

EVENT (0)

This type is reserved for control events, like heartbeats. These can be ignored.

This message is made up of a JSON array where index 0 is the event type – 0in this case. Index 1 is the string containing the body.

Example:

1
2
3
4
[
  0,
  ""
]

This particular message works like a heartbeat to prevent clients from closing the connection if no traffic is detected.

EVENT (1)

The regular event type, it splits into metadata and event data.

This message is made up of a JSON array where:

  • index 0 is the event type – 1 in this case
  • index 1 is the event ID
  • index 2 contains headers – a JSON object containing string keys and string values. This is currently always empty.
  • index 3 is the body of the event. It is a JSON object containing whatever event data was sent, for example it could contain a Chatkit message or user presence update event.

Example:

1
2
3
4
5
6
7
8
9
10
[
  1,
  "3",
  {},
  {
    "example": 1,
    "created": 1489428488,
    "data": {"message": "helloWorld"}
  }
]

EOS (255)

The server will send an end-of-stream (EOS) message to terminate a subscription.

This message is made up of a JSON array where:

  • index 0 is the event type – 255 in this case
  • index 1 is an HTTP status code
  • index 2 contains headers
  • index 3 is the error body. This contains an object with keystype andreason with string values.

Example:

1
2
3
4
5
6
[
  255,
  500,
  {"retry-after": 20},
  {"type": "error type", "reason": "error reason"}
]