Ring Calls

Creating ring calls

The Stream Video API offers a ringing flow that simulates traditional phone calls. This feature lets developers implement call experiences where users can receive incoming calls with ringtones and choose to accept or decline.

You can also show missed call notifications if someone doesn't answer the call on time or is busy in another call.

To start the ringing flow, we need to set the ring flag to true and provide the list of members we want to call. It is important to note that the caller should also be included in the list of members.

Stream API allows reusing call ids (for example, to implement recurring meetings), but this is not something we advise for ring calls. You should create a unique id for every ring call (for example by using UUIDs).

You can set the video flag to true or false (for audio calls), which will control the type of incoming call screen client-side SDKs will display.

// Make sure to use a unique id when creating ring calls
const call = client.video.call("default", crypto.randomUUID());
await call.getOrCreate({
  ring: true,
  video: true, // Set it to `false` for audio calls. This is used to decide what type of incoming call screen is displayed client-side
  data: {
    created_by_id: "myself",
    members: [{ user_id: "myself" }, { user_id: "my friend" }],
  },
});

from getstream.models import CallRequest, MemberRequest
import uuid

# Make sure to use a unique id when creating ring calls
client.video.call("default", uuid.uuid4()).get_or_create(
    data=CallRequest(
        created_by_id=user_id,
        members=[MemberRequest(user_id=alice.id), MemberRequest(user_id=bob.id)],
    ),
    ring=True,
    video=True, #  Set it to `false` for audio calls. This is used to decide what type of incoming call screen is displayed client-side
)

import (
	"github.com/google/uuid"
)

// Make sure to use a unique id when creating ring calls
client.Video().Call("default", uuid.New().String()).GetOrCreate(ctx, &getstream.GetOrCreateCallRequest{
  Ring: getstream.PtrTo(true),
  Video: getstream.PtrTo(true), // Set it to `false` for audio calls. This is used to decide what type of incoming call screen is displayed client-side
  Data: &getstream.CallRequest{
    CreatedByID: getstream.PtrTo("myself"),
    Members: []getstream.MemberRequest{
      {UserID: "myself"},
      {UserID: "my friend"},
    },
  },
})

List<MemberRequest> members = List.of(
  MemberRequest.builder().userID("myself").build(),
  MemberRequest.builder().userID("my friend").build()
);

// Make sure to use a unique id when creating ring calls
var call = new Call("default", UUID.randomUUID().toString(), client.video());
call.getOrCreate(
  GetOrCreateCallRequest.builder()
    .data(
      CallRequest.builder()
        .createdByID("myself")
        .members(members)
        .build()
    )
    .ring(true)
    .video(true) // Set it to `false` for audio calls. This is used to decide what type of incoming call screen is displayed client-side
    .build()
);

CALL_TYPE='default'
# Make sure to use a unique id when creating ring calls
CALL_ID=$(uuidgen)

curl -X POST "https://video.stream-io-api.com/api/v2/video/call/${CALL_TYPE}/${CALL_ID}?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "Content-Type: application/json" \
  -H "stream-auth-type: jwt" \
  -d '{
    "ring": true,
    "video": true,
    "data": {
      "created_by_id": "myself",
      "members": [{ "user_id": "myself" }, { "user_id": "my friend" }]
    }
  }'

Accepting and rejecting ring calls

Accepting and rejecting calls are client-side operations, you can read more about them in SDK documentations.

Ringing individual members

In some cases, you may want to ring individual members instead of the whole call, or you want to ring a member into an existing call. You can do this by using the ring method:

// Make sure to use a unique id when creating ring calls
const call = client.call("default", crypto.randomUUID());
await call.getOrCreate({
  ring: false, // set to false to avoid ringing the whole call
  data: {
    created_by_id: "myself",
    members: [{ user_id: "myself" }, { user_id: "my-friend" }],
  },
});

// note: my-friend needs to be a member of the call
await call.ring({ members_ids: ["my-friend"] });

// to invite a new member and ring them
await call.updateCallMembers({
  update_members: [{ user_id: "my-other-friend" }],
});
await call.ring({ members_ids: ["my-other-friend"] });

// to ring everyone
await call.ring();

# Make sure to use a unique id when creating ring calls
import uuid
from stream_video.types.call import CallRequest, MemberRequest

call_id = str(uuid.uuid4())
call = client.video.call("default", call_id)

call.get_or_create(
    ring=False,  # set to false to avoid ringing the whole call
    data=CallRequest(
        created_by_id="myself",
        members=[
            MemberRequest(user_id="myself"),
            MemberRequest(user_id="my-friend")
        ],
    )
)

# note: my-friend needs to be a member of the call
call.ring(member_ids=["my-friend"])

# to invite a new member and ring them
call.update_call_members(
    update_members=[MemberRequest(user_id="my-other-friend")]
)
call.ring(member_ids=["my-other-friend"])

CALL_TYPE='default'
CALL_ID=$(uuidgen)
ME=myself
SARA=sara
ADAM=adam
JOHN=john

echo "Step 1: Creating a call without ringing..."
curl -X POST "https://video.stream-io-api.com/api/v2/video/call/${CALL_TYPE}/${CALL_ID}?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "Content-Type: application/json" \
  -H "stream-auth-type: jwt" \
  -d "{
    \"ring\": false,
    \"data\": {
      \"created_by_id\": \"${ME}\",
      \"members\": [{ \"user_id\": \"${ME}\" }, { \"user_id\": \"${SARA}\" }]
    }
  }"

echo -e "\n"

echo "Step 2: Ringing sara..."
curl -X GET "https://video.stream-io-api.com/api/v2/video/call/${CALL_TYPE}/${CALL_ID}/ring?api_key=${API_KEY} \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt" \
  -d "{
    \"member_ids\": [\"${SARA}\"],
    \"video\": true
  }"

echo -e "\n"

echo "Step 3: Adding a new members (adam, john)..."
curl -X POST "https://video.stream-io-api.com/api/v2/video/call/${CALL_TYPE}/${CALL_ID}/members?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "Content-Type: application/json" \
  -H "stream-auth-type: jwt" \
  -d "{
    \"update_members\": [{ \"user_id\": \"${ADAM}\" }, { \"user_id\": \"${JOHN}\" }]
  }"

echo -e "\n"

echo "Step 4: Ringing adam and john..."
ENCODED_USER_ADAM=$(echo ${ADAM} | perl -MURI::Escape -lne 'print uri_escape($_)')
ENCODED_USER_JOHN=$(echo ${JOHN} | perl -MURI::Escape -lne 'print uri_escape($_)')
curl -X GET "https://video.stream-io-api.com/api/v2/video/call/${CALL_TYPE}/${CALL_ID}/ring?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt" \
  -d "{
    \"member_ids\": [\"${ADAM}\", \"${JOHN}\"],
    \"video\": true
  }"

// Make sure to use a unique id when creating ring calls
import (
	"github.com/google/uuid"
	getstream "github.com/GetStream/stream-video-go"
)

// Create a new call with a random ID
callID := uuid.NewString()
call := client.Video().Call("default", callID)

// Create user IDs
myself := "myself"
myFriend := "my-friend"
myOtherFriend := "my-other-friend"

// Create call with two members
members := []getstream.MemberRequest{
	{UserID: myself},
	{UserID: myFriend},
}

callRequest := getstream.GetOrCreateCallRequest{
	Ring:        getstream.PtrTo(false), // set to false to
	Data: &getstream.CallRequest{
	avoid ringing the whole call
		CreatedByID: getstream.PtrTo(myself),
		Members:     members,
	},
}

call.GetOrCreate(ctx, &callRequest)

// note: my-friend needs to be a member of the call
call.Ring(ctx, []string{myFriend})

// to invite a new member and ring them
call.UpdateCallMembers(ctx, &getstream.UpdateCallMembersRequest{
	UpdateMembers: []getstream.MemberRequest{
		{UserID: myOtherFriend},
	},
})

// Ring the newly added member
call.Ring(ctx, []string{myOtherFriend})

Ring call events

The ring flow relies on the following events:

call.ring
call.accepted
call.rejected
call.missed

`call.ring` event

This is the start of the ring flow. This event is dispatched to call members when someone starts a call with the ring flag set to true.

It's possible to send push notifications to call members on this event, for more information see Notification settings section

call.ring event reference

`call.accepted` event

This event is dispatched to the call members when a callee accepts an incoming call.

call.accepted event reference

`call.rejected` event

This event is dispatched to the call members when the caller or callee rejects the call.

There are multiple reasons why someone could reject a call (for example, someone explicitly rejecting a call with a "Decline" button is different from someone not answering the call). The call.rejected event contains a reason field to indicate why a call was rejected.

You can pass any string to the reason field, but the Stream API and the SDKs recognize the following values by default:

Name	Description
`rejected`	The callee explicitly rejected the call (for example, with a "Decline" button)
`cancel`	The caller cancelled the call before it was answered. SDKs will also send this event if all callees rejected the call.
`timeout`	1. When a callee is online but doesn't answer the call in `incoming_call_timeout_ms` time. 2. When no callee accepts the call in `auto_cancel_timeout_ms` time, the caller will send this event
`busy`	Signals that the callee is busy. By default, SDKs don't send this reason; integrators can implement this in their own application logic.

call.rejected event reference

`call.missed` event

The call.missed event is dispatched to callees who didn't answer (accept or reject) an incoming call within a given time.

The event is dispatched in the following scenarios:

The callee rejected the call with a timeout or busy reason
When a callee didn't accept or reject the call in missed_call_timeout_ms time (probably the user was offline)
The caller rejected the call with any reason, unless the callee previously rejected the call (declined the call)

It's possible to send push notifications to call members on this event, for more information see Notification settings section

call.missed event reference

Examples

SDKs implement ringing flow in a way that while a call is in the ringing phase, there is no active session. The session starts when the first callee accepts the call.

All accept

Example: Sara calls Ben and Jane. Both Ben and Jane accept the call.

Sara rings Ben and Jane (with ring: true): call.created and call.ring events from Sara to all call members - ringing flow starts
Ben accepts the call: call.accepted event from Ben
Ben joins the call: call.session_started and call.session_participant_joined events
As soon as Ben accepts the call Sara also joins: call.session_participant_joined
Jane also accepts, and joins: call.accepted and call.session_participant_joined
Jane leaves the call: call.participant_left
Ben and Sara also leave: 2x call.participant_left
call.session_ended when inactivity_timeout_seconds elapsed since last participant left the call

Someone rejects

Example: Sara calls Ben and Jane. Ben accepts the call, Jane rejects.

Sara rings Ben and Jane (with ring: true): call.created and call.ring events from Sara to all call members - ringing flow starts
Ben accepts the call: call.accepted event from Ben
Ben joins the call: call.session_started and call.session_participant_joined
As soon as Ben accepts the call Sara also joins: call.session_participant_joined
Jane declines the call: call.rejected event with reason: "decline" from Jane
Ben and Sara leave the call: 2x call.participant_left
call.session_ended when inactivity_timeout_seconds elapsed since last participant left the call

All reject

Example: Sara calls Ben and Jane. Both Jane and Ben reject the call.

Sara rings Ben and Jane (with ring: true): call.created and call.ring events from Sara to all call members - ringing flow starts
Ben declines the call: call.rejected event with reason: "decline" from Ben
Jane is online, but doesn't interact with the incoming call screen: call.rejected event with reason: "timeout" from Jane after incoming_call_timeout_ms elapsed
call.missed is sent to Jane
Since both Ben and Jane rejected the call Sara will reject as well (this is sent from SDKs): call.rejected event with reason: "cancel" from Sara

Caller cancels

Example: Sara calls Ben and Jane, but Sara cancels before anyone answers.

Sara rings Ben and Jane (with ring: true): call.created and call.ring events from Sara to all call members - ringing flow starts
Sara changes her mind, and cancels: call.rejected event with reason: "cancel" from Sara

No one answers the call

Example: Sara calls Ben and Jane, but no one answers.

Sara rings Ben and Jane (with ring: true): call.created and call.ring events from Sara to all call members - ringing flow starts
No one accepts or rejects the call in auto_cancel_timeout_ms time (this can happen if users are offline, and away from their devices): call.rejected event with reason: "timeout" from Sara
call.missed events are sent to both Ben and Jane

Ring call settings

Timeouts

You can control how much time to wait before automatic call rejections and missed call events are dispatched.

These can be set on the call type level or on the call level:

// on call type level
client.video.updateCallType({
  name: callTypeName,
  settings: {
    ring: {
      incoming_call_timeout_ms: 10000,
      auto_cancel_timeout_ms: 15000,
      missed_call_timeout_ms: 15000,
    },
  },
});

// or on call level
call.update({
  settings_override: {
    ring: {
      incoming_call_timeout_ms: 10000,
      auto_cancel_timeout_ms: 15000,
      missed_call_timeout_ms: 15000,
    },
  },
});

# On call type level
client.video.update_call_type(
  name=callTypeName,
  settings={
      "ring": {
        "incoming_call_timeout_ms": 10000,
        "auto_cancel_timeout_ms": 15000,
        "missed_call_timeout_ms": 15000
      }
  }
)

# On call level
call.update(
  settings_override={
      "ring": {
          "incoming_call_timeout_ms": 10000,
          "auto_cancel_timeout_ms": 15000,
          "missed_call_timeout_ms": 15000
      }
  }
)

// Call type level
client.Video().UpdateCallType(ctx, callTypeName, &getstream.UpdateCallTypeRequest{
  Settings: &getstream.CallSettingsRequest{
    Ring: &getstream.RingSettingsRequest{
      IncomingCallTimeoutMs: 10000,
      AutoCancelTimeoutMs:   15000,
      MissedCallTimeoutMs:   getstream.PtrTo(15000),
    },
  },
})

// On call level
call.Update(ctx, &getstream.UpdateCallRequest{
  SettingsOverride: &getstream.CallSettingsRequest{
    Ring: &getstream.RingSettingsRequest{
      IncomingCallTimeoutMs: 10000,
      AutoCancelTimeoutMs:   15000,
      MissedCallTimeoutMs:   getstream.PtrTo(15000),
    },
  },
})

# On call type level
curl -X PUT "https://video.stream-io-api.com/api/v2/video/calltypes/${CALL_TYPE_NAME}?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "ring": {
        "incoming_call_timeout_ms": 10000,
        "auto_cancel_timeout_ms": 15000,
        "missed_call_timeout_ms": 15000
      }
    }
  }'

# On call level
curl -X PATCH "https://video.stream-io-api.com/api/v2/video/call/${CALL_TYPE}/${CALL_ID}?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt" \
  -H "Content-Type: application/json" \
  -d '{
    "settings_override": {
      "ring": {
        "incoming_call_timeout_ms": 10000,
        "auto_cancel_timeout_ms": 15000,
        "missed_call_timeout_ms": 15000
      }
    }
  }'

Push notifications

You can enable/disable push notifications for the call.ring and call.missed events.

client.video.createCallType({
  name: "<call type name>",
  notification_settings: {
    enabled: true,
    call_notification: {
      apns: {
        title: "{{ user.display_name }} calls you",
        body: "{{ user.display_name }} calls you",
      },
      enabled: true,
    },
    call_ring: {
      apns: {
        title: "{{ user.display_name }} calls you",
        body: "{{ user.display_name }} calls you",
      },
      enabled: true,
    },
    call_live_started: {
      enabled: true,
      apns: {
        title: "{{ call.display_name }} started",
        body: "{{ user.display_name }} started",
      },
    },
    call_missed: {
      enabled: true,
      apns: {
        title: "missed call from {{ user.display_name }}",
        body: "missed call from {{ user.display_name }}",
      },
    },
    session_started: {
      enabled: true,
      apns: {
        title: "{{ call.display_name }} started",
        body: "{{ call.display_name }} started",
      },
    },
  },
});

client.video.create_call_type(
  name=call_type_name,
  notification_settings={
      "enabled": True,
      "call_notification": {
          "apns": {
              "title": "{{ user.display_name }} calls you",
              "body": "{{ user.display_name }} calls you"
          },
          "enabled": True
      },
      "call_ring": {
          "apns": {
              "title": "{{ user.display_name }} calls you",
              "body": "{{ user.display_name }} calls you"
          },
          "enabled": True
      },
      "call_live_started": {
          "enabled": True,
          "apns": {
              "title": "{{ call.display_name }} started",
              "body": "{{ user.display_name }} started"
          }
      },
      "call_missed": {
          "enabled": True,
          "apns": {
              "title": "missed call from {{ user.display_name }}",
              "body": "missed call from {{ user.display_name }}"
          }
      },
      "session_started": {
          "enabled": True,
          "apns": {
              "title": "{{ call.display_name }} started",
              "body": "{{ call.display_name }} started"
          }
      }
  }
)

client.Video().CreateCallType(ctx, &getstream.CreateCallTypeRequest{
  Name: "test-call-type",
  NotificationSettings: &getstream.NotificationSettings{
    Enabled: true,
    CallNotification: getstream.EventNotificationSettings{
      APNS: getstream.APNS{
        Title: "{{ user.display_name }} calls you",
        Body:  "{{ user.display_name }} calls you",
      },
      Enabled: true,
    },
    CallRing: getstream.EventNotificationSettings{
      APNS: getstream.APNS{
        Title: "{{ user.display_name }} calls you",
        Body:  "{{ user.display_name }} calls you",
      },
      Enabled: true,
    },
    CallLiveStarted: getstream.EventNotificationSettings{
      Enabled: true,
      APNS: getstream.APNS{
        Title: "{{ call.display_name }} started",
        Body:  "{{ user.display_name }} started",
      },
    },
    CallMissed: getstream.EventNotificationSettings{
      Enabled: true,
      APNS: getstream.APNS{
        Title: "missed call from {{ user.display_name }}",
        Body:  "missed call from {{ user.display_name }}",
      },
    },
    SessionStarted: getstream.EventNotificationSettings{
      Enabled: true,
      APNS: getstream.APNS{
        Title: "{{ call.display_name }} started",
        Body:  "{{ call.display_name }} started",
      },
    },
  },
})

curl -X POST "https://video.stream-io-api.com/api/v2/video/calltypes?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<call type name>",
    "notification_settings": {
      "enabled": true,
      "call_notification": {
        "apns": {
          "title": "{{ user.display_name }} calls you",
          "body": "{{ user.display_name }} calls you"
        },
        "enabled": true
      },
      "call_ring": {
        "apns": {
          "title": "{{ user.display_name }} calls you",
          "body": "{{ user.display_name }} calls you"
        },
        "enabled": true
      },
      "call_live_started": {
        "enabled": true,
        "apns": {
          "title": "{{ call.display_name }} started",
          "body": "{{ user.display_name }} started"
        }
      },
      "call_missed": {
        "enabled": true,
        "apns": {
          "title": "missed call from {{ user.display_name }}",
          "body": "missed call from {{ user.display_name }}"
        }
      },
      "session_started": {
        "enabled": true,
        "apns": {
          "title": "{{ call.display_name }} started",
          "body": "{{ call.display_name }} started"
        }
      }
    }
  }'

Calls

Multi-Tenant & Teams