# Call lifecycle

Depending on your use-case you might want to track special events related to a call, for example the start or end of a call. This guide will list the most notable events related to call lifecycle, and the order in which they sent.

For all call events please refer to the [Events reference](/video/docs/api/webhooks/events/).

For time-sensitive events you can also [set up push notifications](/video/docs/api/call_types/settings/#notification-settings-1) on the call type level.

## Creating a call

When a call is created a `call.created` event is sent to all call members and to the user who created the call.

Calls can be created ahead of time (for example meetings/livestreams in the future). Unless a call is created in backstage mode (more on that below), all users that have `join-call` capability can join the call.

Please note that the Stream API has an upsert behavior, so if you create a call with an ID that already exists, no new call will be created (instead it will be updated), and no `call.created` event will be sent.

[`call.created` event reference](/video/docs/api/webhooks/events/#CallCreatedEvent)

## Ring and notify

You might want to notify users about important calls:

- Ring calls mimic traditional phone calls - we have a separate [Ring call guide](/video/docs/api/ring-calls/) detailing all events (such as `call.ring`) related to ringing.
- If you don't want traditional phone calls, but want to notify members at a given time you can use the [`notify` flag](/video/docs/api/calls/#notify-flag). Setting this flag will send [`call.notification` event](/video/docs/api/webhooks/events/#CallNotificationEvent) to all call members. You can also send push notifications on this event, more information [in the call type settings guide](/video/docs/api/call_types/settings/#notification-settings). You can send multiple `call.notification` events during a call's lifecycle.

## Call sessions

### Starting a session

A call session starts when the first participant joins the call. A `call.session_started` event is sent to all users watching the call.

You can send push notifications when a session has been started, more information [in the call type settings guide](/video/docs/api/call_types/settings/#notification-settings)

[`call.session_started` event reference](/video/docs/api/webhooks/events/#CallSessionStartedEvent)

### Participants

As participants join and leave the call session `call.session_participant_joined` and `call.session_participant_left` events are sent to all users watching the call.

[`call.session_participant_joined` event reference](/video/docs/api/webhooks/events/#CallSessionParticipantJoinedEvent), [`call.session_participant_left` event reference](/video/docs/api/webhooks/events/#CallSessionParticipantLeftEvent)

### Ending a session

A call session ends when the last participant leaves the call and `inactivity_timeout_seconds` elapsed (defaults to 30s). You can set a custom value for `inactivity_timeout_seconds`, more information can be found [here](/video/docs/api/calls/#configuring-custom-session-timeout).

[Ending](#ending-calls) or [deleting](#deleting-calls) a call will also end the session.

[`call.session_ended` event reference](/video/docs/api/webhooks/events/#CallSessionEndedEvent)

### Multiple call sessions

At a given time only one session can be active for a call. But call IDs can be reused (for example, a recurring meeting), so a call can have multiple sessions.

## Backstage mode

If a call type has backstage mode enabled (for example `livestream`), the call will be created in backstage mode, and only users with the `join-backstage` capability can join the call. For more information on backstage, [see the backstage guide](/video/docs/api/streaming/backstage/).

Backstage mode is mainly used in livestream use-cases where hosts might want to gather before/after a stream.

A call can enter and leave backstage mode multiple times.

### Enter backstage mode

When a call enters backstage mode the `call.updated` event is sent to all users watching the call. You can check the `event.call.backstage` field to know if the call is in backstage mode.

When a call type has backstage mode enabled all calls are created in backstage mode. This means that when `call.created` is sent, the call is already in backstage mode (`call.updated` is not sent in this case).

[`call.updated` event reference](/video/docs/api/webhooks/events/#CallUpdatedEvent), [`call.created` event reference](/video/docs/api/webhooks/events/#CallCreatedEvent)

### Leave backstage mode (go live)

When a call goes live the `call.live_started` event is sent to all users watching the call.

You can send push notifications when a call goes live, more information [in the call type settings guide](/video/docs/api/call_types/settings/#notification-settings).

[`call.live_started` event reference](/video/docs/api/webhooks/events/#CallLiveStartedEvent)

## Ending calls

Calls can be ended by using the [end call API endpoint](/video/docs/api/calls/#ending-calls). This operation signals to users that a call isn't supposed to be joined anymore.

If there is an active session when the call is ended, the session will be terminated, and users will be kicked out of the call (`call.session_ended` event sent immediately).

After the session is terminated, the `call.ended` event is sent to all call members.

To join an ended call users need the `join-ended-call` permission.

SDKs won't end calls by default.

[`call.ended` event reference](/video/docs/api/webhooks/events/#CallEndedEvent)

## Deleting calls

When a call is deleted it can no longer be joined, it's also not returned by the Stream API. For more information checkout the [GDPR guide](/video/docs/api/gdpr/calls/).

The call [will be ended](#ending-calls) and then `call.deleted` event will be sent to all users watching the call.

[`call.deleted` event reference](/video/docs/api/webhooks/events/#CallDeletedEvent)

## Examples

Below you will find examples for some common call lifecycle events.

Please note that the examples doesn't show all Stream events, just the ones relevant for call lifecycle. The full list can be found in the [Events reference](/video/docs/api/webhooks/events/).

### Livestream

Example: Sara end Ben host a livestream

1. Sara creates the call: `call.created` event - call is in backstage mode, only hosts can join
2. Sara joins the call: `call.session_started` and `call.session_participant_joined`
3. Ben also joins: `call.session_participant_joined`
4. Hosts are ready to start the livestream: `call.live_started`
5. Livestream ends, hosts return to backstage mode: `call.updated`
6. Ben and Sara leave the call: 2x `call.participant_left`
7. `call.session_ended` when `inactivity_timeout_seconds` elapsed since last participant left the call

### Ring call

<partial id="video/api/_partials/_common_/ring-flow"></partial>

### Meeting with notification

Sara creates a meeting with Ben and Jane, and notifies them.

1. Sara creates a meeting with Ben and Jane (with `notify: true`): `call.created` and `call.notify` events
2. Sara joins the meeting when it's created: `call.session_started` and `call.session_participant_joined`
3. Ben joins as well: `call.session_participant_joined`
4. Then Jane joins: `call.session_participant_joined`
5. The meeting ends, all participants leave the call: 3x `call.participant_left`
6. `call.session_ended` when `inactivity_timeout_seconds` elapsed since last participant left the call

### Recurring meeting

Sara has a weekly meeting with Ben and Jane

1. Sara creates a meeting with Ben and Jane: `call.created` event
2. Ben joins the meeting: `call.session_started` and `call.session_participant_joined`
3. Sara joins as well: `call.session_participant_joined`
4. Then Jane joins: `call.session_participant_joined`
5. The meeting ends, all participants leave the call: 3x `call.participant_left`
6. `call.session_ended` when `inactivity_timeout_seconds` elapsed since last participant left the call

Next week:

1. Jane joins the meeting: `call.session_started` and `call.session_participant_joined`
2. Sara joins as well: `call.session_participant_joined`
3. Then Ben joins: `call.session_participant_joined`
4. The meeting ends, all participants leave the call: 3x `call.participant_left`
5. `call.session_ended` when `inactivity_timeout_seconds` elapsed since last participant left the call

### Ending a call

You might have noticed that no examples contained a `call.ended` event so far. That's because by default calls are not ended, only when the end call endpoint is explicitly called. Let's see an example for this:

1. Sara creates a meeting with Ben and Jane: `call.created` event
2. Sara joins the meeting when it's created: `call.session_started` and `call.session_participant_joined`
3. Ben joins as well: `call.session_participant_joined`
4. Then Jane joins: `call.session_participant_joined`
5. Sara ends the call: `call.session_ended` and `call.ended` events are sent

---

This page was last updated at 2025-08-15T14:16:36.154Z.

For the most recent version of this documentation, visit [https://getstream.io/video/docs/api/call-lifecycle/](https://getstream.io/video/docs/api/call-lifecycle/).