Third Party In-Chat Calling

LAST EDIT Nov 21 2022

Stream applications can be configured to use external video providers such as 100ms and Agora. This makes it very easy to add in-chat-calling to your application without creating a server-side integration on your side.

We are working on making example projects available showcasing a third party video integration with both 100ms and Agora.

Setting up your application with an external provider

Copied!

First of all you need to setup Stream Chat with your video provider. At the moment Stream integrates directly with Agora and 100ms.

When you use one of these providers, you can initiate calls from chat without any server-side support on your side. The configuration can be done via Dashboard, CLI or API. You can find detailed information about each provider later in this document.

Initiating a call from Chat

Copied!

Chat users can initiate a call directly from a channel. To do this you need to use the Create Call endpoint.

Only users with the create-call permission can use this endpoint. Open a support request to recieve this permission.

The Create Call API call returns a call object and an authentication token. The call object contains the information needed for users to join the call to your provider. You can embed this information inside a message attachment, channel event or attach it to the channel.

Calls have two required parameter: id and type. Calls are unique based on their id value, when a call with the same id is found we will re-use that one instead of returning an error or creating a new one. This is very convenient if you want to ensure that only one call exists for one channel. The type field can be set to “video” or “audio”.

You can safely store the entire call object inside a message, in fact that’s the simplest way to integrate in-chat-calls.

Notifying users

Copied!

There are several ways you can use to notify other users about the call:

  1. You can send a message on the channel and include the call object inside an attachment

  2. You can store the call object inside the channel

  3. You can send a custom event on the channel

In the last two cases the user(s) will receive an event which you can use to display the UI needed to join the call. Message attachments can be easily customized to show a call UI.

You can see real app examples using Agora and 100ms here.

CreateCall API Endpoint

Copied!

Body Parameters

Copied!

nametypedescriptiondefaultoptional
idstring

A unique identifier to assign to the call. The id is case-insensitive. Accepted characters are a-z, A-Z, 0-9, and . - : _ If not provided, this is generated automatically.

options

object

Additional options that are passed to the video provider.

Empty object

Response

Copied!

Name

Type

Description

call

Call Object

token

string

The provider token needed to join the call for the user that created the call.

agora_uid

float

The Agora uid needed to join the call for the requesting user. This field is only present when agora is used. It is safe to expect this value to always be an unsigned integer.

agora_app_id

string

The Agora app_id

Call object

Copied!

name

type

description

provider

string

The video provider used to host the call. This can be hms or agora.

id

string

The unique identifier for the call. This ID is used to retrieve user tokens.

agora

object

An object containing the information needed to identify and open the call using Agora SDK. At the moment channel is the only field included in this object.

hms

object

An object containing the information needed to identify and open the call using 100ms SDK. At the moment room_id and room_name are the only two fields included in this object.

Join a call from Chat

Copied!

Users can join an existing call using the information stored inside a channel (eg. message attachment). Chat users can use the GetCallToken to obtain the authentication token for a call.

Only users with the join-call permission can retrieve a token with this endpoint.

The authentication token is retrieved by using the id of the call as returned inside the call object by the Create Call endpoint.