livedigital Chat API Client Integration Guide

This document describes integration with livedigital Chat API from client perspective. You can find full API methods list in Swagger spec.

Chat client app interacts with livedigital Chat API and optionally with App server depending on authentication scheme.

Chat client workflow

1. Authenticate

To start using Chat API, client should have chat user token. There are two authentication schemes described in Authentication.

2. Subscribe to instant events

When chat user is authenticated, they request a token for socket connection via GET /centrifuge-token (TODO: paste a link to swagger spec) method. User connects to Chat Socket API via Centrifuge client.

TODO: which Centrifuge channels to observe?

3. Fetch current state

After subscribing to instant events but before starting to apply incoming state changes, user must synchronize his client state to current server state.

TODO: How to fetch current state: channels and messages.

4. Handle instant events

Client receives events via Centrifuge and applies corresponding chat state changes. All incoming state changes must be applied in strict order. In general case, each incoming event represents valid state change only when applied on top of previous consistent state. Skipping or reordering events may lead to inconsistent state, which will require full resync between client and server.

Consider a case when events are applied concurrently or are enqued and applied out of original order:

5. Join a channel

User can send and receive messages only in channels they have previously joined. To join a channel, user calls POST /channels/join method.

6. Send a message

User sends messages via POST /messages/send method.