Session Timers

A session timer allows you to limit the maximum duration of a call. The duration can be configured for all calls of a certain type, or on a per-call basis. When a session timer reaches zero, the call automatically ends.

Creating a call with a session timer

Let’s see how to create a single call with a limited duration:

const callType = "default";
const callId = "test-call";

const call = client.call(callType, callId);
await call.getOrCreate({
  data: {
    settings_override: {
      limits: {
        max_duration_seconds: 3600,
      },
    },
  },
});

This code creates a call with a duration of 3600 seconds (1 hour) from the time the session is starts (a participant joins the call).

After joining the call with the specified max_duration_seconds, you can examine a session’s timer_ends_at field, which provides the timestamp when the call will end. When a call ends, all participants are removed from the call.

await call.join();
console.log(call.state.session?.timer_ends_at);

Extending a call

​You can also extend the duration of a call, both before or during the call. To do that, you should use the call.update method:

await call.get();
// extend by 1 minute
const duration = call.state.settings?.limits.max_duration_seconds + 60;

await call.update({
  settings_override: {
    limits: {
      max_duration_seconds: duration,
    },
  },
});

If the call duration is extended, the timer_ends_at is updated to reflect this change. Call participants will receive the call.updated event to notify them about this change.