Querying Calls

The Stream Video SDK allows you to query calls and watch them. This allows you to build apps that display feeds of calls with real-time updates (without joining them).

You can query calls based on built-in fields as well as any custom field you add to the calls. Multiple filters can be combined using AND, OR logical operators, each filter can use its comparison (equality, inequality, greater than, greater or equal, etc.).

You can use the StreamVideoClient to query for:

  • Upcoming calls
  • Calls that are currently live
  • Popular live streams / audio rooms with a link to the recording

Client API

You can query calls by using the client directly by using the following API:

const { calls } = await client.queryCalls({
  filter_conditions: { ...filters },
  sort: [...sortOptions],
  limit: 25,
  watch: true,
});

Filters

Filter expressions support multiple match criteria, and it’s also possible to combine filters. You can filter on the following fields:

FieldDescription
idThe id for this call
cidThe cid for this call. IE: default:123
teamThe team id for the call.
typeThe call type. Typically default, livestream etc…
created_by_user_idThe user id who created the call
created_atWhen the call was created
updated_atWhen the call was updated
ended_atWhen the call ended
starts_atWhen the call starts at
backstageIf the call is in backstage mode or not
membersCheck if the call has these members listed
ongoingCheck if the call is ongoing or not
customYou can query custom data using the "custom.myfield" syntax

For more information, visit the filter operators guide. Or check the examples:

Calls that are about to start

In this snippet, you can see how you can query for calls that have livestream type and are about to start 30 minutes from now:

import { StreamVideoClient } from "@stream-io/video-react-native-sdk";

let client: StreamVideoClient;

const inNext30mins = new Date(Date.now() + 1000 * 60 * 60 * 30);

const { calls } = await client.queryCalls({
  filter_conditions: {
    type: { $eq: "livestream" },
    starts_at: { $gt: inNext30mins.toISOString() },
  },
  sort: [{ field: "starts_at", direction: -1 }],
  limit: 10,
  watch: true,
});

Call filters on a custom property

import { StreamVideoClient } from "@stream-io/video-react-native-sdk";

let client: StreamVideoClient;

const { calls } = await client.queryCalls({
  filter_conditions: { "custom.color": "red" },
  limit: 10,
  watch: true,
});

Calls that are ongoing / currently have participants

import { StreamVideoClient } from "@stream-io/video-react-native-sdk";

let client: StreamVideoClient;

const { calls } = await client.queryCalls({
  filter_conditions: { ongoing: true },
});

Calls the user has created or is a member of

import { StreamVideoClient } from "@stream-io/video-react-native-sdk";

let client: StreamVideoClient;

const { calls } = await client.queryCalls({
  filter_conditions: {
    $or: [
      { created_by_user_id: "<user id>" },
      { members: { $in: ["<user id>"] } },
    ],
  },
  limit: 10,
  watch: true,
});

Sorting

The SortParamRequest model contains two properties: field and direction.

The direction can be 1 for ascending and -1 for descending, while the field can be one of the following values:

FieldDescription
starts_atWhen the call starts at
created_atWhen the call was created
updated_atWhen the call was updated
ended_atWhen the call ended
typeThe call type. Typically default, livestream etc…
idThe id for this call
cidThe cid for this call. IE: default:123
import { StreamVideoClient } from "@stream-io/video-react-native-sdk";

let client: StreamVideoClient;

const { calls } = await client.queryCalls({
  sort: [{ field: "starts_at", direction: -1 }],
  limit: 10,
  watch: true,
});

It’s possible to provide multiple sort parameters:

import { StreamVideoClient } from "@stream-io/video-react-native-sdk";

let client: StreamVideoClient;

const { calls } = await client.queryCalls({
  sort: [
    { field: "starts_at", direction: -1 },
    { field: "created_at", direction: 1 },
  ],
  limit: 10,
  watch: true,
});

Watching calls

If you specify watch: true as an option, the SDK will create a subscription to the call data on the server and you’ll be able to receive updates in real-time.

The server will send updates to the client when the call data changes (for example, members are updated, a call session has started, etc…). This is useful for showing a live preview of who is in the call or building a call dashboard.

Pagination

You can specify the page size using the limit option. The API response will include links to the previous/next pages. The following code example shows how pagination works:

import { StreamVideoClient } from "@stream-io/video-react-native-sdk";

let client: StreamVideoClient;

const inNext30mins = new Date(Date.now() + 1000 * 60 * 60 * 30);
const callQuery = {
  filter_conditions: {
    type: { $eq: "livestream" },
    starts_at: { $gt: inNext30mins.toISOString() },
  },
  sort: [{ field: "starts_at", direction: -1 }],
  limit: 10,
  watch: true,
};

let { calls, prev, next } = await client.queryCalls(callQuery);

// Go to the next page
({ calls, prev, next } = await client.queryCalls({ ...callQuery, next }));

// Go to the previous page
({ calls, prev, next } = await client.queryCalls({ ...callQuery, prev }));
© Getstream.io, Inc. All Rights Reserved.