Creating & Updating Users

Last Edit: Sep 24 2020

Stream Chat exposes a set user method that automatically creates and updates the user. Please note that the setUser 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.

The updateUsers endpoint creates or update users. Any user present in the payload, will have its data replaced with the new version. When used from backend, you can send up to 100 users per API request.

For example:


const response = await client.setUser(
    { 
        id: userID, 
        role: 'admin', 
        favorite_color: 'green'
    },
    token
);
// user object is now {id: userID, role: 'user', favorite_color: 'green'}
// note how you are not allowed to make the user admin via this endpoint
const updateResponse = await serverClient.updateUsers([{ 
    id: userID, 
    role: 'admin', 
    book: 'dune'
 }]);
// user object is now {id: userID, role: 'admin', book: 'dune'}
// note how the user became admin and how the favorite_color field was removed
                    

# user object is now {id: userID, role: 'admin', book: 'dune'}
client.update_users([{"id": user_id, "role": "admin", "book": "dune"}])
                    

# user object is now {id: userID, role: 'admin', book: 'dune'}
client.update_users([{ :id => userID, :role => 'admin', :book => 'dune'}])
                    

//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']]);
                    

client.updateUser(user).enqueue(result -> {
    User updatedUser = result.data();
    return Unit.INSTANCE;
});
                    

// user object is now {id: userID, role: 'admin', book: 'dune'}
client.UpdateUsers([]User{
    {ID: userID, Role: "admin", ExtraData: map[string]interface{}{"book": "dune"}},
})
                    

let user = User(id: "bob")
Client.shared.update(user: user) { (result) in
	// Handle the result
}
                    

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 });
                    

await client.updateUser(user);
                    

val user = User(userId)
client.updateUser(user).enqueue { 
    val user = it.data()
}
                    
The updateUser (server-side) method has permission to make a user an admin; however, the setUser (client-side) method does not have permission. This is because the setUser 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.

Partial Update

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:


// 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);
                    

# 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)
                    

# at the moment this is not supported on Ruby
                    

// at the moment this is not supported on PHP
                    

// at the moment we don't have a Java client for server side usage
                    

// at the moment this is not supported on Go// Partial update is not supported in Swift SDK
                    

// Partial update is not supported in Swift SDK