Creating & Updating Users

LAST EDIT Apr 26 2021

Client-side User Creation


Stream Chat exposes a connectUser method that automatically creates and updates the user. Please note that the connectUser call has some limitations:

For example, if you're looking to sync your user base, you'll want to use the update users endpoint from backend and send users in bulk.

Server-side User Updates (Batch)


The upsertUsers function creates or updates users, and accepts batch of users. Any user present in the payload will have its data replaced with the new version. (see below for partial updates) You can send up to 100 users per API request in both upsertUsers and partialUpdateUser.

For example (with a single user):

The updateUser (server-side) method has permission to make a user an admin; however, the connectUser (client-side) method does not have permission. This is because the connectUser method is called client-side, and for security reasons, you cannot edit a user's role from the client. The second difference is that the updateUser call can remove fields. This is why the favorite_color property in the above example is removed after the update is called.

And for a batch of users, simply add additional entries (up to 100) into the array you pass to upsertUsers:

If any user in a batch of users contains an error, the entire batch will fail, and the first error encountered will be returned.

Server-side Partial Update (Batch)


If you need to update a subset of properties for a user(s), you can use a partial update method. Both set and unset parameters can be provided to add, modify, or remove attributes to or from the target user(s). The set and unset parameters can be used separately or combined.

Please see below for an example:

Partial updates support batch requests, similar to the updateUser endpoint.

Unique Usernames


Clients can set a username, by setting the name custom field. The field is optional and by default has no uniqueness constraints applied to it, however this is configurable by setting the enforce_unique_username to either app, team or no.

When checking for uniqueness, the name is normalized, by removing any white-space or other special characters, and finally transforming it to lowercase. So "John Doe" is considered a duplicate of "john doe", "john.doe", etc.

Enabling this setting will only enforce the constraint going forward and will not try to validate existing usernames.

When this setting is set to app, attempts to create or update a user with an existing name in this app, will fail with duplicate username error.

When set to team, attempts to create or update a user with an existing name will fail only if the name already exists within a common team.