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 to 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, enabling push notifications, 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.

Resource Deletion

Users and Rooms are deleted using asynchronous deletion jobs. When submitting a delete request, a job is created and the status of this job can be queried. Shortly after the job is created the User or Room will be locked, which prevents updates on the resource.

The actual deletion will proceed thereafter, and can take significant time depending on the number of messages that need deleting. Previous versions of the API provided synchronous endpoints for deletion, which required long running connections, which could fail under various conditions. If you are using the synchronous endpoints you should upgrade to the latest version, as the synchronous endpoints will be deprecated in a future version.

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 are made up of one or more parts, where each part has a MIME type, and one of:

  • Inline string content
  • A link (URL)
  • An attached piece of media

Note that currently messages can only be edited by the server SDKs.


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 across connections, as well as subscribing to receive updates to other member's cursors in realtime.

Unread Counts

Rooms that the current user is a member of will be annotated with an unread count, which will be kept up to date when new messages are sent or read, without having to subscribe to the room. The unread count is the number of messages in the room after the user’s most recently sent Read Cursor.

If a user has not explicitly set a cursor, then it is assumed that they haven’t read any of the messages in the room. For example, a room with 42 messages and no cursors set will have an unread count of 42.

Read State

A read state object contains a user’s read cursor and unread count for a room.

Read states are included in the following events on the user subscription endpoint:

  • initial_state event
  • added_to_room event
  • read_state_updated event

Push Notifications

When Chatkit users on iOS or Android devices miss a private message, they can receive it as a push notification. The message will appear as a push notification on their lock screen which they can tap to launch the app and return to the conversation. Find out more in the overview or setup your iOS or Android app to receive Chatkit push notifications.


  • Currently messages can only be edited by the server SDKs.


Usage limits are detailed below:

  • Max users in a room: 500
  • Max inline part size: 5KB
  • Max total inline size per message: 6KB
  • Max parts per message: 10
  • 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: 321 characters
  • Max user ID length: 160 characters
  • Max attachment file size: 5MB

We appreciate that our current limits may seem limiting for your use-case. We are committed to building it to increasingly support more use-cases, so if something feels like a design limitation for your application, we'd love to hear from you so please contact us