Select your Platform:
Client SDKs
Backend SDKs
Creating & Updating Users
Confused about "Creating & Updating Users"?
Let us know how we can improve our documentation:
Client-side User Creation
Copied!Confused about "Client-side User Creation"?
Let us know how we can improve our documentation:
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)
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):
1
2
3
4
5
6
const updateResponse = await serverClient.upsertUser({
id: userID,
role: 'admin',
book: 'dune'
});
// user object is now {id: userID, role: 'admin', book: 'dune'}
1
2
# user object is now {id: userID, role: 'admin', book: 'dune'}
client.update_users([{"id": user_id, "role": "admin", "book": "dune"}])
1
2
# user object is now {id: userID, role: 'admin', book: 'dune'}
client.update_users([{ :id => userID, :role => 'admin', :book => 'dune'}])
1
2
3
4
5
//update a single user with updateUser
$client->updateUser(['id' => 'bob-1', 'role' => 'admin', 'book' => 'dune']);
//update multiple users with updateUsers by passing an array of users
$client->updateUsers([['id' => 'bob-1', 'role' => 'admin', 'book' => 'dune']]);
1
2
3
4
client.updateUser(user).enqueue(result -> {
User updatedUser = result.data();
return Unit.INSTANCE;
});
1
2
3
4
// user object is now {id: userID, role: 'admin', book: 'dune'}
client.UpdateUsers([]User{
{ID: userID, Role: "admin", ExtraData: map[string]interface{}{"book": "dune"}},
})
1
2
3
4
5
6
7
8
9
10
11
12
import StreamChat
chatClient.currentUserController().updateUserData(
name: "Bob",
imageURL: URL(string: "https://bob.com/image.png")!,
userExtraData: nil
) { error in
if let error = error {
// handle error
print(error)
}
}
1
2
3
4
5
6
7
8
9
var user = new User()
{
ID = "bob-1",
Role = Role.Admin,
};
user.SetData("book", "dune");
// user object is now {id: userID, role: 'admin', book: 'dune'}
await client.Users.UpdateMany(new User[] { user });
1
await client.updateUser(user);
1
2
3
4
val user = User(userId)
client.updateUser(user).enqueue {
val user = it.data()
}
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
:
1
2
3
4
5
6
const updateResponse = await serverClient.upsertUsers([
{ id: userID1, role: 'admin', book: 'dune'},
{ id: userID2, role: 'user', book: '1984'},
{ id: userID3, role: 'admin', book: 'Fahrenheit 451'}
]);
// each user object is updated accordingly
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:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
// make partial update call for userID
// it set's user.role to "admin", sets user.field = {'text': 'value'}
// and user.field2.subfield = 'test'.
//
// NOTE:
// changing role is available only for server-side auth.
// field name should not contain dots or spaces, as dot is used as path separator.
const update = {
id: "userID",
set: {
role: "admin",
field: {
text: 'value'
},
'field2.subfield': 'test',
},
unset: ['field.unset'],
};
// response will contain user object with updated users info
const response = await client.partialUpdateUser(update);
// partial update for multiple users
const updates = [{
id: "userID",
set: {
field: "value"
}
}, {
id: "userID2",
unset: ["field.value"],
}];
// response will contain object {userID => user} with updated users info
const response = await client.partialUpdateUsers(updates);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
# make partial update call for userID
# it set's user.role to "admin", sets user.field = {'text': 'value'}
# and user.field2.subfield = 'test'.
# NOTE:
# changing role is available only for server-side auth.
# field name should not contain dots or spaces, as dot is used as path separator.
update = {
"id": "userID",
"set": {
"role": "admin",
"field": {
"text": 'value'
},
'field2.subfield': 'test',
},
"unset": ['field.unset'],
};
# response will contain user object with updated users info
client.update_user_partial(update);
# partial update for multiple users
updates = [
{
"id": "userID",
"set": {"field": "value"}
},
{
"id": "userID2",
"unset": ["field.value"]
}
]
# response will contain object {userID => user} with updated users info
client.update_users_partial(updates)
1
# at the moment this is not supported on Ruby
1
// at the moment this is not supported on PHP
1
// at the moment we don't have a Java client for server side usage
1
// at the moment this is not supported on Go// Partial update is not supported in Swift SDK
1
// Partial update is not supported in Swift SDK
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.
1
2
3
4
// Enable uniqueness constraints on App level
await client.updateAppSettings({
enforce_unique_usernames: 'app',
});
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.
1
2
3
4
// Enable uniqueness constraints on Team level
await client.updateAppSettings({
enforce_unique_usernames: 'team',
});
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.