Users

The Stream user object is central to every product and appears in many API responses, effectively following the user throughout the platform. Only an id is required to create a user but you can store additional custom data. We recommend only storing what is necessary, such as a username and image URL.

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.

Users are also created on the fly when they connect from a client-side SDK, with the user role. However, it is also common to add your users to Stream before going live and keep properties of your user base in sync. For this you'll want to use the upsertUsers function server-side and send users in bulk.

The upsertUser method creates or updates a user, replacing its existing data with the new payload (see below for partial updates). To create or update users in batches of up to 100, use the upsertUsers or partialUpdateUsers APIs, which accept an array of user objects.

const updateResponse = await serverClient.upsertUser({
  id: userID,
  role: "admin",
  book: "dune",
});

from getstream.models import UserRequest

client.upsert_users(UserRequest(id=user_id, role="admin", custom={"book": "dune"}))

Models = GetStream::Generated::Models

client.common.update_users(
  Models::UpdateUsersRequest.new(
    users: { user_id => Models::UserRequest.new(id: user_id, role: 'admin', custom: { 'book' => 'dune' }) }
  )
)

client.UpdateUsers(ctx, &getstream.UpdateUsersRequest{
	Users: map[string]getstream.UserRequest{
		userID: {ID: userID, Role: getstream.PtrTo("admin"), Custom: map[string]any{"book": "dune"}},
	},
})

// dotnet add package getstream-net
using GetStream;
using GetStream.Models;

var client = new StreamClient("{{ api_key }}", "{{ api_secret }}");

await client.UpdateUsersAsync(new UpdateUsersRequest
{
    Users = new Dictionary<string, UserRequest>
    {
        ["bob-1"] = new UserRequest
        {
            ID = "bob-1",
            Role = "admin",
            Custom = new Dictionary<string, object> { ["book"] = "dune" }
        }
    }
});

client.updateUsers(UpdateUsersRequest.builder()
    .users(Map.of(userId1, UserRequest.builder().id(userId1).role("admin").build()))
    .build()).execute();

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

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

from getstream.models import UserRequest

client.upsert_users(
    UserRequest(id=user_id1, role="admin", custom={"book": "dune"}),
    UserRequest(id=user_id2, role="user", custom={"book": "1984"}),
    UserRequest(id=user_id3, role="admin", custom={"book": "Fahrenheit 451"}),
)

Models = GetStream::Generated::Models

client.common.update_users(
  Models::UpdateUsersRequest.new(
    users: {
      user_id1 => Models::UserRequest.new(id: user_id1, role: 'admin', custom: { 'book' => 'dune' }),
      user_id2 => Models::UserRequest.new(id: user_id2, role: 'user', custom: { 'book' => '1984' }),
      user_id3 => Models::UserRequest.new(id: user_id3, role: 'admin', custom: { 'book' => 'Fahrenheit 451' }),
    }
  )
)

client.UpdateUsers(ctx, &getstream.UpdateUsersRequest{
	Users: map[string]getstream.UserRequest{
		userID1: {ID: userID1, Role: getstream.PtrTo("admin"), Custom: map[string]any{"book": "dune"}},
		userID2: {ID: userID2, Role: getstream.PtrTo("user"), Custom: map[string]any{"book": "1984"}},
		userID3: {ID: userID3, Role: getstream.PtrTo("admin"), Custom: map[string]any{"book": "Fahrenheit 451"}},
	},
})

// dotnet add package getstream-net
using GetStream;
using GetStream.Models;

var client = new StreamClient("{{ api_key }}", "{{ api_secret }}");

await client.UpdateUsersAsync(new UpdateUsersRequest
{
    Users = new Dictionary<string, UserRequest>
    {
        [userId1] = new UserRequest { ID = userId1, Role = "admin" },
        [userId2] = new UserRequest { ID = userId2, Role = "user" },
        [userId3] = new UserRequest { ID = userId3, Role = "admin" }
    }
});

client.updateUsers(UpdateUsersRequest.builder()
    .users(Map.of(
        userId1, UserRequest.builder().id(userId1).role("admin").build(),
        userId2, UserRequest.builder().id(userId2).role("admin").build(),
        userId3, UserRequest.builder().id(userId3).role("admin").build()))
    .build()).execute();

Partial updates

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.

// partial update for a single user setting and unsetting multiple fields
const update = {
  id: "userID",
  set: {
    role: "admin",
    field: {
      text: "value",
    },
    "field2.subfield": "test",
  },
  unset: ["field.unset"],
};

const response = await client.partialUpdateUser(update);

// partial update for multiple users
const updates = [
  {
    id: "userID",
    set: {
      field: "value",
    },
  },
  {
    id: "userID2",
    unset: ["field.value"],
  },
];

const response = await client.partialUpdateUsers(updates);

from getstream.models import UpdateUserPartialRequest

# partial update for a single user
client.update_users_partial(users=[
    UpdateUserPartialRequest(
        id="userID",
        set={
            "role": "admin",
            "field": {"text": "value"},
            "field2.subfield": "test",
        },
        unset=["field.unset"],
    )
])

# partial update for multiple users
client.update_users_partial(users=[
    UpdateUserPartialRequest(id="userID", set={"field": "value"}),
    UpdateUserPartialRequest(id="userID2", unset=["field.value"]),
])

Models = GetStream::Generated::Models

# partial update for a single user
client.common.update_users_partial(
  Models::UpdateUsersPartialRequest.new(
    users: [Models::UpdateUserPartialRequest.new(
      id: 'userID',
      set: {
        'role' => 'admin',
        'field' => { 'text' => 'value' },
        'field2.subfield' => 'test',
      },
      unset: ['field.unset']
    )]
  )
)

# partial update for multiple users
client.common.update_users_partial(
  Models::UpdateUsersPartialRequest.new(
    users: [
      Models::UpdateUserPartialRequest.new(id: 'userID', set: { 'field' => 'value' }),
      Models::UpdateUserPartialRequest.new(id: 'userID2', unset: ['field.value']),
    ]
  )
)

use GetStream\GeneratedModels as Models;

$client->updateUsersPartial(new Models\UpdateUsersPartialRequest(
    users: [new Models\UpdateUserPartialRequest(
        id: $userId,
        set: (object)["role" => "admin", "field2.subfield" => "test"],
        unset: ["field.unset"],
    )]
));

resp, err := client.UpdateUsersPartial(ctx, &getstream.UpdateUsersPartialRequest{
	Users: []getstream.UpdateUserPartialRequest{
		{
			ID: user.ID,
			Set: map[string]any{
				"role": "admin",
				"field": map[string]any{
					"text": "value",
				},
			},
		},
	},
})

// dotnet add package getstream-net
using GetStream;
using GetStream.Models;

var client = new StreamClient("{{ api_key }}", "{{ api_secret }}");

await client.UpdateUsersPartialAsync(new UpdateUsersPartialRequest
{
    Users = new List<UpdateUserPartialRequest>
    {
        new UpdateUserPartialRequest
        {
            ID = userId,
            Set = new Dictionary<string, object>
            {
                ["role"] = "admin",
                ["field2.subfield"] = "test"
            },
            Unset = new List<string> { "field.unset" }
        }
    }
});

client.updateUsersPartial(UpdateUsersPartialRequest.builder()
    .users(List.of(UpdateUserPartialRequest.builder()
        .id(user.getId())
        .set(Map.of("role", "admin", "field2.subfield", "test"))
        .build()))
    .build()).execute();

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 or team.

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.

With the setting at app, creating or updating a user fails if the username already exists anywhere in the app. With team, it only fails if the username exists within the same team.

// Enable uniqueness constraints on App level
await client.updateAppSettings({
  enforce_unique_usernames: "app",
});

// Enable uniqueness constraints on Team level
await client.updateAppSettings({
  enforce_unique_usernames: "team",
});

# Enable uniqueness constraints on App level
client.update_app(enforce_unique_usernames="app")

# Enable uniqueness constraints on Team level
client.update_app(enforce_unique_usernames="team")

Models = GetStream::Generated::Models

# Enable uniqueness constraints on App level
client.common.update_app(
  Models::UpdateAppRequest.new(enforce_unique_usernames: 'app')
)

# Enable uniqueness constraints on Team level
client.common.update_app(
  Models::UpdateAppRequest.new(enforce_unique_usernames: 'team')
)

use GetStream\GeneratedModels as Models;

// Enable uniqueness constraints on App level
$client->updateApp(new Models\UpdateAppRequest(
    enforceUniqueUsernames: "app",
));

// Enable uniqueness constraints on Team level
$client->updateApp(new Models\UpdateAppRequest(
    enforceUniqueUsernames: "team",
));

// Enable uniqueness constraints on App level
resp, err := client.UpdateApp(ctx, &getstream.UpdateAppRequest{
	EnforceUniqueUsernames: getstream.PtrTo("app"),
})

// Enable uniqueness constraints on Team level
resp, err = client.UpdateApp(ctx, &getstream.UpdateAppRequest{
	EnforceUniqueUsernames: getstream.PtrTo("team"),
})

// dotnet add package getstream-net
using GetStream;
using GetStream.Models;

var client = new StreamClient("{{ api_key }}", "{{ api_secret }}");

// Enable uniqueness constraints on App level
await client.UpdateAppAsync(new UpdateAppRequest
{
    EnforceUniqueUsernames = "app"
});

// Enable uniqueness constraints on Team level
await client.UpdateAppAsync(new UpdateAppRequest
{
    EnforceUniqueUsernames = "team"
});

// Enable uniqueness constraints on App level
client.updateApp(UpdateAppRequest.builder()
    .enforceUniqueUsernames("app")
    .build()).execute();

// Enable uniqueness constraints on Team level
client.updateApp(UpdateAppRequest.builder()
    .enforceUniqueUsernames("team")
    .build()).execute();

Querying users

You can query and filter users using the queryUsers endpoint. This allows you to search for users based on various criteria such as custom fields, roles, and other user properties.

const response = await client.queryUsers({
  payload: {
    filter_conditions: {
      role: "admin",
    },
    sort: [{ field: "created_at", direction: -1 }],
    limit: 10,
    offset: 0,
  },
});

console.log(response.users);

from getstream.models import QueryUsersPayload, SortParamRequest

response = client.query_users(
    payload=QueryUsersPayload(
        filter_conditions={
            "role": "admin",
        },
        sort=[
            SortParamRequest(field="created_at", direction=-1)
        ],
        limit=10,
        offset=0,
    )
)

payload = GetStream::Generated::Models::QueryUsersPayload.new(
  filter_conditions: {
    'role' => 'admin',
  },
  sort: [
    {
      'field' => 'created_at',
      'direction' => -1,
    },
  ],
  limit: 10,
  offset: 0,
)

response = client.common.query_users(payload)

$response = $client->queryUsers(
    new GeneratedModels\QueryUsersPayload(
        filterConditions: (object)['role' => 'admin'],
        sort: [
            ['field' => 'created_at', 'direction' => -1]
        ],
        limit: 10,
        offset: 0
    )
);

response, err := client.QueryUsers(context.Background(), &getstream.QueryUsersRequest{
    Payload: &getstream.QueryUsersPayload{
        FilterConditions: map[string]any{
            "role": "admin",
        },
        Sort: []getstream.SortParamRequest{
            {
                Field:     getstream.PtrTo("created_at"),
                Direction: getstream.PtrTo(-1),
            },
        },
        Limit:  getstream.PtrTo(10),
        Offset: getstream.PtrTo(0),
    },
})

var response = await client.QueryUsersAsync(
    new QueryUsersRequest
    {
        Payload = new QueryUsersPayload
        {
            FilterConditions = new Dictionary<string, object>
            {
                ["role"] = "admin"
            },
            Sort = new[]
            {
                new SortParamRequest
                {
                    Field = "created_at",
                    Direction = -1
                }
            },
            Limit = 10,
            Offset = 0
        }
    }
);

Map<String, Object> filterConditions = new HashMap<>();
filterConditions.put("role", "admin");

QueryUsersRequest request = QueryUsersRequest.builder()
    .payload(QueryUsersPayload.builder()
        .filterConditions(filterConditions)
        .sort(List.of(
            SortParamRequest.builder()
                .field("created_at")
                .direction(-1)
                .build()
        ))
        .limit(10)
        .offset(0)
        .build())
    .build();

QueryUsersResponse response = client.queryUsers(request).execute().getData();

Supported Filters

Query Users Performance

Query Users runs on an indexed user database. To keep response times predictable for apps of every size, filters that cannot use an index are rejected with a 400 error.

Custom fields only support exact matches. Custom properties are stored in a JSON column, and the index on that column only supports exact-match lookups. Range operators such as $gt, $gte, $lt, and $lte (as well as $in, $exists, and $contains) on a custom field cannot use the index and would require scanning every user in your app, so they are not allowed. If you need range queries on a field, consider using one of the built-in indexed fields (such as created_at, updated_at, or last_active), or query your own database instead.

Not-equal operators are only allowed on id and boolean fields. The $ne, $nin, and $nor operators are only supported on the id field (and $ne on boolean fields such as banned). On other fields these negative filters prevent the database query planner from using an index: instead of seeking directly to matching rows, it has to walk through everything that does not match, which can result in slow queries and timeouts.

Supported Sort

You can sort results by specifying a field and direction (1 for ascending, -1 for descending).

Supported Options

The options for the queryUsers method are primarily used for pagination.

Querying with Autocomplete

You can use the $autocomplete operator to search for users by name or ID with partial matching.

const response = await client.queryUsers({
  payload: {
    filter_conditions: {
      name: { $autocomplete: "ro" },
    },
  },
});

from getstream.models import QueryUsersPayload

client.query_users(
    QueryUsersPayload(filter_conditions={"name": {"$autocomplete": "ro"}})
)

Models = GetStream::Generated::Models

client.common.query_users(
  Models::QueryUsersPayload.new(
    filter_conditions: { 'name' => { '$autocomplete' => 'ro' } }
  )
)

use GetStream\GeneratedModels as Models;

$response = $client->queryUsers(new Models\QueryUsersPayload(
    filterConditions: (object)["name" => (object)['$autocomplete' => "ro"]],
));

Querying Inactive Users

You can use the last_active field with the $exists operator to find users who have never connected. Use $exists: false for users who have never been active, or $exists: true for users who have connected at least once.

const response = await client.queryUsers({
  payload: {
    filter_conditions: {
      id: { $in: [activeUser, neverActiveUser] },
      last_active: { $exists: false },
    },
  },
});

from getstream.models import QueryUsersPayload

users = client.query_users(
    QueryUsersPayload(filter_conditions={"last_active": {"$exists": False}})
)

Deactivating and deleting users

Depending on your use case, you can choose to delete users or deactivate them. There are some differences between these two approaches.

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

Both bulk deletion and bulk deactivation are performed asynchronously by the 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 a single user
client.deactivate_user(user_id=user_id)

# Deactivating users in bulk is performed asynchronously
response = client.deactivate_users(
    user_ids=[user_id, user_id_2]
)

# Reactivate users
client.reactivate_users(
    user_ids=[user_id, user_id_2]
)

// Deactivating a single user
$client->deactivateUser(
    'user1',
    new GeneratedModels\DeactivateUserRequest()
);

// Deactivating users in bulk is performed asynchronously
$response = $client->deactivateUsers(
    new GeneratedModels\DeactivateUsersRequest(
        userIds: ['user1', 'user2']
    )
);

// Reactivate users
$client->reactivateUsers(
    new GeneratedModels\ReactivateUsersRequest(
        userIds: ['user1', 'user2']
    )
);

// Deactivating a single user
_, err = client.DeactivateUser(context.Background(), "user1", &getstream.DeactivateUserRequest{})

// Deactivating users in bulk is performed asynchronously
_, err = client.DeactivateUsers(context.Background(), &getstream.DeactivateUsersRequest{
    UserIds: []string{"user2"},
})

// Reactivate users
_, err = client.ReactivateUsers(context.Background(), &getstream.ReactivateUsersRequest{
    UserIds: []string{"user1", "user2"},
})

// Deactivating a single user
await client.DeactivateUserAsync(userId, new DeactivateUserRequest());

// Deactivating users in bulk is performed asynchronously
var deactivateRequest = new DeactivateUsersRequest
{
    UserIds = new[] { userId, userId2 }
};
await client.DeactivateUsersAsync(deactivateRequest);

// Reactivate users
var reactivateRequest = new ReactivateUsersRequest
{
    UserIds = new[] { userId, userId2 }
};
await client.ReactivateUsersAsync(reactivateRequest);

// Deactivating a single user
client.deactivateUser(userId, DeactivateUserRequest.builder().build()).execute();

// Deactivating users in bulk is performed asynchronously
DeactivateUsersRequest deactivateRequest = DeactivateUsersRequest.builder()
    .userIds(List.of(userId, userId2))
    .build();
client.deactivateUsers(deactivateRequest).execute();

// Reactivate users
ReactivateUsersRequest reactivateRequest = ReactivateUsersRequest.builder()
    .userIds(List.of(userId, userId2))
    .build();
client.reactivateUsers(reactivateRequest).execute();

Deactivating users in bulk can take some time. Monitor the returned task ID as described in Async operations.

Deleting users

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

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

# Delete users
client.delete_users(user_ids=["<id>"])

# Restore users
client.restore_users(user_ids=["<id>"])

# Delete users
client.delete_users(
  GetStream::Generated::Models::DeleteUsersRequest.new(
    user_ids: ['<id>']
  )
)

# Restore users
client.restore_users(
  GetStream::Generated::Models::RestoreUsersRequest.new(
    user_ids: ['<id>']
  )
)

// Delete users (soft delete by default)
$client->deleteUsers(
    new GeneratedModels\DeleteUsersRequest(
        userIds: ['<id>']
    )
);

// Restore users
$client->restoreUsers(
    new GeneratedModels\RestoreUsersRequest(
        userIds: ['<id>']
    )
);

// Delete users
deleteRequest := &getstream.DeleteUsersRequest{
    UserIds: []string{"<id>"},
}
_, err = client.DeleteUsers(context.Background(), deleteRequest)

// Restore users
restoreRequest := &getstream.RestoreUsersRequest{
    UserIds: []string{"<id>"},
}
_, err = client.RestoreUsers(context.Background(), restoreRequest)

// Delete users
await client.DeleteUsersAsync(new DeleteUsersRequest
{
    UserIds = new List<string> { "<id>" }
});

// Restore users
await client.RestoreUsersAsync(new RestoreUsersRequest
{
    UserIds = new List<string> { "<id>" }
});

// Delete users
client.deleteUsers(
    DeleteUsersRequest.builder()
        .userIds(Arrays.asList("<id>"))
        .build()
).execute();

// Restore users
client.restoreUsers(
    RestoreUsersRequest.builder()
        .userIds(Arrays.asList("<id>"))
        .build()
).execute();

You can delete up to 100 users per call. The user parameter controls what happens to the user object itself:

Each product adds parameters that control what happens to the user's product data, such as their messages, channels and calls. These are documented with each product: see deleting many users in chat and deleting users in video.

Exporting or deleting user data to meet compliance requests is covered on GDPR and privacy.

Restoring deleted users

If users are soft deleted, they can be restored using the server-side client. However, only the user's metadata is restored; product data such as memberships, messages and reactions is not restored.

You can restore up to 100 users per call:

await client.restoreUsers(["userID1", "userID2"]);

client.restore_users(user_ids=["userID1", "userID2"])