Core Concepts

User-Centric Chat

All interactions between clients (users on mobile apps or web browsers) and the Chatkit servers are performed through a user object. Often referred to as currentUser in the documentation. Operations such as creating rooms, subscribing a rooms, and sending messages are all done through this object.

Chat Manager

All Client SDKs include the concept of a chat manager. This chat manager will be your entry point for interacting with Chatkit. It's the object that you'll need to initialise with your Chatkit instance ID and token provider. Once you've created a chat manager you'll then use it to connect the device to the Chatkit servers.

Token Provider

This term encompasses two components:

  • A token provider endpoint is a service which you expose on your server. It authenticates requests against your own system and responds with a signed token that specifies the requesting user's identity.
  • A token provider object (PPTokenProvider) is a component which you implement and pass to the SDK. It is responsible for querying your token provider endpoint, supplying any information you need to authenticate the request, and returning a token to the Chatkit SDK via a standardised interface.

In summary, you provide a token provider object to the SDK. The SDK will expect this object to supply signed tokens for the current user on request. Usually your token provider object will achieve this by making a network request to the token provider endpoint which you host on your server.

Current User

Upon successful connection to the Chatkit servers you'll have access to a user object, for example the Swift PCCurrentUser object. This then becomes the focal point for further interactions with the Chatkit service.

The user object is used to take actions such as creating rooms, sending messages, and sending typing indicators, amongst other things.


Each user can be a member of many rooms. Rooms can be used for 1-1 chats or group chats; Chatkit does not differentiate between the two concepts at the room level.

The users who are members of a room can change over time: new users may choose to join a room (assuming they have the appropriate permissions), and users may choose to leave a room.

You can create either private or public rooms:

  • Public rooms are visible to and can be joined by all users, by default.
  • Private rooms are only visible to the members of the room and cannot be joined by default. Instead a user needs the appropriate permissions to be able to join the room, or they need to be added to it by someone else with appropriate permissions.


Users identify who the members of a room are, as well as who sent a message or created a room. At a minimum a user has an ID, a creation timestamp, and a last update timestamp. You can also add a name to users, as well as an avatar URL.

The ID of a user must be unique and must also be something that won't change over the lifetime of your app. For example, if you already have a store of users for your app and they each have a unique, permanent username or numerical ID then when you're creating users in the Chatkit system you should use the username or ID as the user ID in the Chatkit system.

You also have the option to set any other custom data you wish to store for a user in their custom_data property. However, currently whenever a change is made to any of a user's properties, they will not propagate to other connected users instantaneously. Users will instead receive new information about an updated user either when the SDK fetches information about the user in the background, or if a user disconnects and reconnects.

Room Membership

A user has to be a member of a room in order to interact with it. To become a member of a room, a user must join that room. Room membership is persistent, so a user remains a member of the room until they explicitly leave (or are removed).

Subscribing to a room implicitly joins the subscribing user to the room, and allows clients to receive updates in realtime. A user is only subscribed to a room as long as they have an open connection, but they remain a member of the room after they disconnect.


Every message belongs to a single room and has an associated user, which is the user that sent the message. Messages can contain a text component and / or an attachment. The attachment can represent any kind of file, or it can be a plain link.

Note that currently messages cannot be edited.


Authentication is the process of verifying the identity of a user. This is done by providing clients with signed tokens that Chatkit can verify with every request. The following diagram shows the authentication flow:

A valid token is required with every request. To achieve this you'll need two things:

  • A token provider in your client code so that the client has a method for requesting a token.
  • Unless you're implementing a custom authentication flow, an endpoint on a server (that you run), which will return a valid token to the client upon request.

More detailed documentation on the authentication process can be found here.

Roles and Permissions

Once Chatkit authenticates a user's request and verifies their identity, it must then decide if that user has permission to perform the requested action. This is where the roles and permissions process comes in. Users are assigned roles, which contain a set of permissions describing what actions they can and cannot do. Chatkit will check the user's roles before carrying out the requested action.

When a user makes a request to the Chatkit servers, the user ID is first extracted from the token that accompanies the request. Using that user ID, the user's roles and their associated permissions are retrieved. The permissions required for the request are then compared against the set of permissions that the user has been given, as determined by their roles, and the request is either permitted or rejected.

You can head over to the roles and permissions page to find out more.

Read Cursors

Optionally, clients can report how far through the messages in a room they have read by setting a read cursor. Clients can then keep track of their own cursors accross connections, as well as subscribing to receive updates to other member's cursors in realtime.


  • Currently messages cannot be edited.


Usage limits are detailed below:

  • Max users in a room: 100
  • Max message size: 5KB
  • Max custom_data size when creating users: 5KB
  • Max number of messages retrieved on resuming a room subscription: 100
  • Max number of users which can be added or removed from a room in a single request: 10
  • Max room name length: 60 characters
  • Max user ID length: 160 characters
  • Max file size: 5MB
  • Max attachment size: 5 MB

Did you find this document useful?

We are always striving to create the most accurate and informative docs as possible. If there is something especially wrong (or right) here then please let us know.