Skip to main content

Get started

Stream powers Chat Messaging, Video & Audio, and Activity Feeds for billions of global end-users across thousands of different apps.

Stream’s global edge network ensures a faster and more reliable experience for your video calls and livestreams. Excellent developer experience and docs enable you to build in-app video calling in days. Scale to millions of users and thousands of call participants.

For the average Stream integration, the development work focuses on code that executes in the client. However, some tasks must be executed from the server for safety (for example, token generation).

Stream provides server-side SDKs to help execute these tasks.

You can reference our development roadmap to know which languages and features are supported.

Installation​

All official SDKs are available on package managers, full source code is available on the GetStream Github organization.

npm install @stream-io/node-sdk
// or using yarn
yarn add @stream-io/node-sdk

Something doesn't work? You can open a GitHub issue:

Creating client​

To create a server-side client, you'll need your API key and secret. Both of them can be found in your Stream Dashboard.

You can optionally pass a timeout for the API requests, the default timeout is 3000ms.

import { StreamClient } from '@stream-io/node-sdk';
// or
// const { StreamClient } = require("@stream-io/node-sdk");

const apiKey = '';
const secret = '';
client = new StreamClient(apiKey, secret);

// optionally add timeout to API requests
// the default timeout is 3000ms
client = new StreamClient(apiKey, secret, { timeout: 3000 });

Creating users and user tokens​

To create a user you need to provide an ID, and their role. Optionally you can also specify their name and an image, these fields are recognized and rendered by the default SDK components. It's also possible to add any other custom data.

Tokens need to be generated server-side. Typically, you integrate this into the part of your codebase where you log in or register users. The tokens provide a way to authenticate a user or give access to a specific set of video/audio calls.

const userId = 'john';
const newUser: UserRequest = {
  id: userId,
  role: 'user',
  custom: {
    color: 'red',
  },
  name: 'John',
  image: 'link/to/profile/image',
};
await client.upsertUsers({
  users: {
    [newUser.id]: newUser,
  },
});

// exp is optional (by default the token is valid for an hour)
const exp = Math.round(new Date().getTime() / 1000) + 60 * 60;

client.createToken(userId, exp);

Creating a call​

You can create a call by providing the call type and an ID:

  • The call type controls which features are enabled and sets up permissions. Call type settings and permissions can be set from API, or using the Stream Dashboard.
  • Calls IDs can be reused, which means they can be joined multiple times, so it's possible to set up recurring calls.

You can specify call members who can receive push notification about the call.

It's also possible to store any custom data with the call object.

const callType = 'default';
const callId = 'my-first-call';
const call = client.video.call(callType, callId);

call.create({ data: { created_by_id: 'john' } });

// optionally provide additional data
call.create({
  data: {
    created_by_id: 'john',
    // Call members need to be existing users
    members: [{ user_id: 'john', role: 'admin' }, { user_id: 'jack' }],
    custom: {
      color: 'blue',
    },
  },
});

// Upsert behavior
call.getOrCreate({data: /* */});

Call types​

Call types provide sensible default settings for different use-cases. We provide the following types out of the box:

  • Default (default) for 1:1 or group calls that use both video and audio
  • Livestreaming (livestream) to build ultra low latency livestreaming for your app on our global edge network. Broadcast from your phone or RTMP and scale to millions of participants.
  • Audio room (audio_room) to build audio experiences for your app. You can build basic calling or feature rich experience like Twitter spaces. Audio quality, reliability and scalability is far ahead of competing solutions.

Each of our SDKs have tutorials specific for each call type. If you want to know the default settings for each of the call types check out the Built-in call types page.

It's possible to tweak the built-in call types or create new ones.

Call members​

You can provide a list of call members. Call members need to be existing users. Every call member has a call-level role, you can configure roles on the call type.

Call members can receive push notifications.

// Call members need to be existing users
call.updateCallMembers({
  // You can add new members
  // You can also update the role of existing members
  update_members: [{ user_id: 'sara' }, { user_id: 'emily', role: 'admin' }],
});

You can also remove call members:

call.updateCallMembers({
  remove_members: ['sara'],
});

Updating a call​

Default call settings are inherited from the call type. These settings can be overridden if necessary.

call.update({
  settings_override: {
    audio: { mic_default_on: true, default_device: 'speaker' },
  },
});

// or to update custom data
call.update({ custom: { color: 'red' } });

Did you find this page helpful?