How do I migrate users and add new users to Stream Chat?

This article will cover how to migrate existing users as well as how to add and connect new users to Stream Chat. If you have any further questions, please reach out to support at support@getstream.io.

1. Existing Users

Existing users should be added to Stream with user credentials from your database and the Stream server-side batch endpoint upsertUsers (docs). For each user, you will want to use their unique userID, as well as add any other relevant data (e.g. application user role, custom metadata, etc.).

Note: Two users may have the same name, but every must have a own unique user ID

With upsertUsers, you will be able to add 100 users at a time, for up to 10k per minute with base rate limits. Below is an example of how to use this endpoint to add 3 users at once with the JS SDK:

const addUsersResponse = await serverClient.upsertUsers([ 
     { id: userID1, role: 'admin', book: 'Hardy Boys'}, 
     { id: userID2, role: 'user', book: 'Tin Tin'}, 
     { id: userID3, role: 'admin', book: 'Romeo and Juliet'} 
 ]);

2. New Users

The most common approach for creating new users in Stream is with unique userIDs that are also pulled from your database or written to it in real time.

Connect new user to Chat when they sign up for your service

If you would like to connect a user to Chat when they sign up, you can take their new userID, create a token for authentication server-side, and then call connectUser (docs). The connectUser endpoint will create them as a user in Stream and connect the user to Chat, so they may start sending and receiving messages immediately. 

Below is a quick example of connectUser, this is also thoroughly detailed in our docs (note the required userID and auth token):

await chatClient.connectUser( 
    { 
        id: userID, 
        name: 'Tim Lee', 
        image: 'https://getstream.io/random_svg/?name=TimLee', 
    }, 
'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoicm91bmQtZmlyZWZseS0zIn0.LhM-nGxSnGagQ0KL6ljr8Kx_KWp-3EyTrnfQYWXkoHI', 

);

Add new user to Stream when they sign up, but wait to connect Chat

If your service does not require Chat upon sign up/sign in, you can wait to connect the user to Chat, but still create the user in Stream with upsertUser (docs) upon sign up. This will create them as a user, but not open a websocket connection and allow them to use Chat yet. This may be handy for certain use case and reducing unnecessary MAU/Concurrent Connections. You can call connectUser, like in the above section, when you wish to connect them to Chat. The below code shows an example of how to use upsertUser with the JS SDK:

const addUserResponse = await serverClient.upsertUser({
     id: 'tim', 
     role: 'admin', 
     book: 'Romeo and Juliet' 
});

Review

To migrate users to Stream, you can use the upsertUsers batch endpoint with userIDs and credentials from your database. This can add 100 users per API call and 10k+ users per minute based on your rate limits. When adding new users you can select when you add and connect them based on business needs. Users can be added and connected when they sign up for your service with connectUser or simply added without connecting to Chat by using upsertUser.

Related articles:

Stream Chat Basic Guide

Stream Chat Glossary

Stream Chat Checklist

Token Creation Best Practices