User management

Creating users

When creating users, there are a few important things to keep in mind:

• The id field is mandatory, in most cases you want this to be the same ID you use on your database.
• The role field is optional, by default it is set to user but you can specify any existing role.
• Custom data can be added to users in the custom field.
• name and image are optional and handled by all SDKs automatically to render users.

const newUser: UserRequest = {
  id: 'user-id',
  role: 'user',
  custom: {
    color: 'red',
  },
  name: 'This is a test user',
  image: 'link/to/profile/image',
};
await client.upsertUsers([newUser]);

Updating users

You can update users in two ways:

• Replace updates: replace the entire user object with the one provided to the API call
• Partial update: choose which fields you want to change

const user: UserRequest = {
  id: 'userid',
  role: 'user',
  custom: {
    color: 'blue',
  },
  name: 'This is a test user',
  image: 'link/to/profile/image',
};
client.upsertUsers([user]);

// or
client.updateUsersPartial({
  users: [
    {
      id: user.id,
      set: {
        'new-field': 'value',
      },
      unset: ['name'],
    },
  ],
});

Anonymous users

Anonymous users are users that are not authenticated. It’s common to use this for watching a livestream or similar where you aren’t authenticated. Anonymous users can be connected using client-side SDKs. Anonymous users are not counted toward your MAU.

Guest users

Guest users are temporary user accounts. You can use it to temporarily give someone a name and image when joining a call. Guest users can be created client-side. Guest users are counted towards your MAU usage.

Deactivating and deleting users

Depending on your use-case, you can choose to delete users or de-activating them. There are some differences between these two approach.

Deactivating users:

• the user will not be allowed to perform API requests / connect
• user data is retained on Stream’s side and returned from API
• deactivated users can be re-activated

Deleting users:

• the user will no longer be able to perform API requests / connect
• the user is deleted and by default not returned from API
• all data from the user is marked as deleted
• by default the data is retained and “soft” deleted, you can optionally request hard deletion
• deletion is not reversible

Note: Both deletion and deactivation are performed asynchronously by Stream API. A task ID is returned and you can use that to check the status of its processing.

Deactivating users

client.deactivateUser({
  user_id: '<id>',
});

// reactivate
client.reactivateUsers({
  user_ids: ['<id>'],
});

// deactivating users in bulk is performed asynchronously
const deactivateResponse = client.deactivateUsers({
  user_ids: ['<id1>', '<id2>'...],
});

Deactivating users in bulk can take some time, this is how you can check the progress:

// Example of monitoring the status of an async task
// The logic is same for all async tasks
const response = await client.exportUsers({
  user_ids: ["<user id1>", "<user id1>"],
});

// you need to poll this endpoint
const taskResponse = await client.getTask({ id: response.task_id });

console.log(taskResponse.status === "completed");

Deleting users

client.deleteUsers({ user_ids: ["<id>"] });

//restore
client.restoreUsers({ user_ids: ["<id>"] });

The delete users endpoints supports the following parameters to control which data needs to be deleted and how. By default users and their data are soft-deleted.

Deleting users in bulk can take some time, this is how you can check the progress:

// Example of monitoring the status of an async task
// The logic is same for all async tasks
const response = await client.exportUsers({
  user_ids: ["<user id1>", "<user id1>"],
});

// you need to poll this endpoint
const taskResponse = await client.getTask({ id: response.task_id });

console.log(taskResponse.status === "completed");