Skip to main content
Version: 1.1

Holding a call

The hold/unhold feature allows you to pause or resume media transmission and reception while maintaining the connection.

  • When a user holds a call
    • Media transmission and reception is paused.
    • The peer is notified of the hold state and the user's media status changes through events.
  • When the user unholds a call
    • Media transmission and reception is resumed.
    • The peer is notified of the unhold state and the user's media status changes through events.
Supported call typeMinimum SDK version
1-to-1 call, group call (conference)0.7

1-to-1 call​

To hold or unhold a 1-to-1 call, use hold() or unhold() of PlanetKitCall.

After you call hold() to pause the application's transmission and reception of media streams, the peer should wait for unhold() to be called in order to resume communication. On the peer side, the application lets PlanetKit play a hold tone that was set in the call parameter.

The following diagram shows the flow of holding and unholding a 1-to-1 call.

1-to-1 call hold sequence diagram

API overview​

The following APIs are related to holding and unholding a call in 1-to-1 calls.

MethodDescriptionRelated event callbacks
hold()Starts hold state. You can provide the hold reason.onPeerHold
unhold()Stops hold state.onPeerUnhold

Sample code​

The following shows how to implement the feature to hold and unhold a group call.

Holding or unholding a call​

// Hold the call, with optional reason
Future<void> holdCall(PlanetKitCall call) async {
  final bool holdResult = await call.hold(
    reason: 'User requested', // Optional reason string
  );
  print('hold result=$holdResult');
}

// Unhold the call
Future<void> unholdCall(PlanetKitCall call) async {
  final bool unholdResult = await call.unhold();
  print('unhold result=$unholdResult');
}
// Implement related callbacks of the PlanetKitCallEventHandler class
final PlanetKitCallEventHandler callEventHandler = PlanetKitCallEventHandler()
  ..onPeerHold = (PlanetKitCall call, String? reason) {
    // This is called after the peer places the call on hold.
    // Write your own code here.
  }
  ..onPeerUnhold = (PlanetKitCall call) {
    // This is called after the peer resumes the call from hold.
    // Write your own code here.
  };

Relationship with other features​

Here are some points to consider regarding other media control features.

Enabling and disabling a video call​

A client that holds a call (Client 01) cannot request the enabling or disabling of a video call.

However, the peer client (Client 02) can request the enabling or disabling of a video call using the enableVideo() and disableVideo() methods. In 1-to-1 calls, enabling and disabling a video call are always processed simultaneously on both sides. Therefore, when Client 02 requests the enabling or disabling of a video call, both Client 02 and Client 01 will perform enabling or disabling of a video call accordingly. After that, the Client 01, which was previously on hold, will continue to remain on hold.

Screen share​

During screen share, if the client of the presenter (the user who is doing screen share) calls hold(), the screen share is stopped and the following event is generated:

  • Peer: onPeerScreenShareStopped

Group call​

To hold or unhold a group call, use hold() or unhold() of PlanetKitConference.

In group calls, the hold behavior is different from 1-to-1 calls. The key differences are as follows:

  • In 1-to-1 calls, media transmission and reception are paused for both users, but in group calls, only the media transmission and reception of the user who holds the call are paused.
  • There is no concept of hold tone.

The following diagram shows the flow of holding and unholding a group call.

Group call hold sequence diagram

API overview​

The following APIs are related to holding and unholding a call in group calls.

MethodDescriptionRelated event callbacks
hold()Starts hold state. You can provide the hold reason.onPeersHold
unhold()Stops hold state.onPeersUnhold

Sample code​

The following shows how to implement the feature to hold and unhold a group call.

Holding or unholding a call​

// Hold the conference, with optional reason
Future<void> holdConference(PlanetKitConference conference) async {
  final bool holdResult = await conference.hold(
    reason: 'User requested', // Optional reason string
  );
  print('conference hold result=$holdResult');
}

// Unhold the conference
Future<void> unholdConference(PlanetKitConference conference) async {
  final bool unholdResult = await conference.unhold();
  print('conference unhold result=$unholdResult');
}
// Implement related callbacks of the PlanetKitConferenceEventHandler class
final PlanetKitConferenceEventHandler conferenceEventHandler =
    PlanetKitConferenceEventHandler()
      ..onPeersHold = (
        PlanetKitConference conference,
        List<PeerHoldData> peers,
      ) {
        // This is called after the conference is placed on hold.
        // Write your own code here.
      }
      ..onPeersUnhold = (
        PlanetKitConference conference,
        List<PlanetKitConferencePeer> peers,
      ) {
        // This is called after the conference is resumed from hold.
        // Write your own code here.
      };

Relationship with other features​

Here are some points to consider regarding other media control features.

Enabling and disabling a video call​

A client that holds a call (Client 01) cannot request the enabling or disabling of a video call.

Screen share​

During screen share, if the client of the presenter (the user who is doing screen share) calls hold(), the screen share is stopped and the following event is generated:

  • Peers: onScreenShareUpdate of PlanetKitPeerControlHandler (DISABLED state)

APIs related to holding and unholding a call are as follows.

1-to-1 call​

Methods​

Events​

Group call​

Methods​

Events​