Select your Platform:
Managing Users
Confused about "Managing Users"?
Let us know how we can improve our documentation:
Stream Users require only an id to be created. Users can be created with role of user or admin. The role will be set to user if a value is not provided in the request. There are additional properties you can provide to further describe your users.
If you wish to have users join a chat before they have created an account, check out our Anonymous User support
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 upsertUsers function server side and send users in bulk.
Server-side User Updates (Batch)
Copied!Confused about "Server-side User Updates (Batch)"?
Let us know how we can improve our documentation:
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):
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:
Server-side Partial Update (Batch)
Copied!Confused about "Server-side Partial Update (Batch)"?
Let us know how we can improve our documentation:
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:
Unique Usernames
Copied!Confused about "Unique Usernames"?
Let us know how we can improve our documentation:
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.
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.
Exporting Users
Copied!Confused about "Exporting Users"?
Let us know how we can improve our documentation:
To export user data, Stream Chat exposes an exportUser method. This method can only be called server-side due to security concerns, so please keep this in mind when attempting to make the call.
Below is an example of how to execute the call to export user data:
The export will return all data about the user, including:
User ID
Messages
Reactions
Custom Data
Deactivate a User
Copied!Confused about "Deactivate a User"?
Let us know how we can improve our documentation:
To deactivate a user, Stream Chat exposes a deactivateUser method. This method can only be called server-side due to security concerns, so please keep this in mind when attempting to make the call.
Deactivated users cannot:
Connect to Stream Chat
Send or receive messages
(deactivated users can be reactivated, see below)
Below is an example of how to execute the call to deactivateUser:
mark_messages_deleted parameter is optional. This parameter will delete all messages associated with the user. If you would like to keep message history, ensure that mark_messages_deleted is set to false. To remove all messages related to the user, set the value to true.The response will contain an object with the user ID that was deactivated. Further, the user will no longer be able to connect to Stream Chat as an error will be thrown.
To reinstate the user as active, use the reactivateUser method by passing the users ID as a parameter:
Delete a User
Copied!Confused about "Delete a User"?
Let us know how we can improve our documentation:
To delete user data, Stream Chat exposes a deleteUser method. Once a user has been deleted, it cannot be un-deleted and the user_id cannot be used again. This method can only be called server-side due to security concerns, so please keep this in mind when attempting to make the call.
Below is an example of how to execute the call to deleteUser:
mark_messages_deleted parameter is optional. This parameter will delete all messages associated with the user. If you would like to keep message history, ensure that mark_messages_deleted is set to false. To remove all messages related to the user, set the value to true.To perform a "hard delete" on the user, you must set mark_messages_deleted to true and provide an additional parameter called hard_delete with the value set to true. This method will delete all messages, reactions, and any other associated data with the user. Another option is delete_conversation_channels, if set true the deleted user is removed from all one-to-one channels.
After deleting or hard deleting a user, the user will no longer be able to:
Connect to Stream Chat
Send or receive messages
Be displayed when querying users
Have messages stored in Stream Chat (depending on whether or not
mark_messages_deletedis set totrueorfalse)