Initialization & Users

LAST EDIT Jul 10 2024

The code below creates a chat client instance for browser/mobile usage. Additional options, such as API base URL and request timeouts, can be provided to the client.Setting.

Connecting the User

Copied!

Once initialized, you must specify the current user with connectUser:

Note how we are waiting for the connectUser API call to be completed before moving forward. You should always make sure to have the user set before making any more calls. All SDKs make this very easy and wait or queue requests until then.

Connect User Parameters

Copied!
nametypedescriptiondefaultoptional
userobjectThe user object. Must have an id field. User Ids can only contain characters a-z, 0-9, and special characters @ _ and - It can have as many custom fields as you want, as long as the total size of the object is less than 5KB
userTokenstringThe user authentication token. See Tokens & Authentication for details default

WebSocket Connections

Copied!

The connectUser (or SDK equivalent) function performs several operations when used. Please note that this method should never be used server-side.

  1. Creates a new user if the user_id is not already registered with the application, incrementing the monthly active users

  2. Updates the user in the application (will add/modify existing fields but will not overwrite/delete previously set fields unless the key is used)

  3. Opens a WebSocket connection and increments the Concurrent Connections for the application

The React-native, iOS, Android, and Flutter SDK's handle WebSocket disconnection logic, but if a manual disconnect is required in your application, then there are the following options

XHR Fallback

Copied!

Most browsers support WebSocket connections as an efficient mode of real-time data transfer. However, sometimes the connection cannot be established due to network or a corporate firewall. In such cases, the client will establish or switch to XHR fallback mechanisms and gently poll our service to keep the client up-to-date.

The fallback mechanism can be enabled with the flag enableWSFallback

Privacy Settings

Copied!

Additionally, when connecting the user, you can include the privacy_settings as part of the user object.

Let's have a closer look on the parameters:

nametypedescriptiondefaultoptional
typing_indicatorsobjectif enabled is set to false, then typing.start and typing.stop events will be ignored for this user and these events will not be sent to othersenabled: true
read_receiptsobject

If enabled is set to false, then the read_state of this user will not be exposed to others. Additionally, read_state related events will not be delivered to others when this user reads messages.

enabled: true