Core Concepts

Setup Overview

A typical setup comprises of three components:

  • Chatkit: The Pusher service that your clients will connect to for their chat functionality.
  • Clients: Your many happy users loving their new chat functionality.
  • Your server: Used for clients to request authentication tokens and to make admin requests to Chatkit.

User-Centric Chat

All interactions between clients, for example mobile apps, and the Chatkit servers, are performed through a connected user. In practice this means:

  • sending a message is modelled as a connected user adding a message to a room
  • a user should subscribe to a room to receive new messages from that room
  • a user should join a room as opposed to instructing a room to add a user to itself

In practical terms, the code you'd write for this last example looks like this (if you are using Swift!):

currentUser.joinRoom(id: 123) { room, error in
    // ...

as opposed to something like this:

myRoom.addUser(id: "sarah") { room, error in
    // ...

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 or deleted.


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 or deleted.


There are certain limits that will be in place at least for the beta, 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 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.