Skip to main content
Version: 6.2

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.

The behavior of holding and unholding a call differs depending on the call type. This page describes how you can hold or unhold a call.

Supported call typeMinimum SDK version
1-to-1 call, group call (conference)PlanetKit 3.0
Note

Prior to PlanetKit 5.5, holding/unholding a call did not directly affect the operation of camera. Starting with PlanetKit 5.5, however, the camera is controlled by holding/unholding as follows:

  • When you hold a call, PlanetKit turns off the camera and disables video transmission, making the camera indicator turned off.
  • When you unhold a call, PlanetKit turns on the camera and enables video transmission, making the camera indicator turned on.
Note

Prior to PlanetKit 6.0, holding/unholding a call did not directly affect the operation of microphone. Starting with PlanetKit 6.0, however, the microphone is controlled by holding/unholding as follows:

  • When you hold a call, PlanetKit turns off the microphone and disables audio transmission, making the microphone indicator turned off.
  • When you unhold a call, PlanetKit turns on the microphone and enables audio transmission, making the microphone indicator turned on.

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 in a 1-to-1 call.

1-to-1 call hold sequence diagram

API overview​

The following APIs are used for 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 1-to-1 call.

Holding or unholding a call​

val call: PlanetKitCall

... // Obtain the PlanetKitCall instance from the result of makeCall() or verifyCall()

// Hold the call
val holdResult = call.hold(
    reason = "User requested", // Optional reason string
    callback = object : PlanetKitRequestCallback { param ->
        Log.d(TAG, "hold result=${param.isSuccessful}")
    }
)

// Unhold the call
val unholdResult = call.unhold(
    userData = null, // Optional user data to pass to callback
    callback = object : PlanetKitRequestCallback { param ->
        Log.d(TAG, "unhold result=${param.isSuccessful}")
    }
)
// Implement related callbacks of the CallListener interface
// MakeCallListener for caller and AcceptCallListener for callee
private val makeAcceptCallListener = object : MakeCallListener, AcceptCallListener {
    ...

    override fun onPeerHold(call: PlanetKitCall, reason: String?) {
        // This is called after the call is placed on hold.
        // Write your own code here.
    }

    override fun onPeerUnhold(call: PlanetKitCall) {
        // This is called after the call 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.

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 events are generated:

  • Presenter: onMyScreenShareStoppedByHold
  • 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 in a group call.

Group call hold sequence diagram

API overview​

The following APIs are used for 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​

val conference: PlanetKitConference

... // Obtain the PlanetKitConference instance from the result of joinConference()

// Hold the conference
val holdResult = conference.hold(
    reason = "User requested", // Optional reason string
    callback = object : PlanetKitRequestCallback { param ->
        Log.d(TAG, "hold result=${param.isSuccessful}")
    }
)

// Unhold the conference
val unholdResult = conference.unhold(
    userData = null, // Optional user data to pass to callback
    callback = object : PlanetKitRequestCallback { param ->
        Log.d(TAG, "unhold result=${param.isSuccessful}")
    }
)
// Implement related callbacks of the ConferenceListener interface
private val conferenceListener = object : ConferenceListener {
    ...

    override fun onPeersHold(
        conference: PlanetKitConference,
        peerHoldReceivedList: List<PlanetKitConferencePeerHoldReceivedParam>
    ) {
        // This is called after the conference is placed on hold.
        // Write your own code here.
    }

    override fun onPeersUnhold(conference: PlanetKitConference, peers: List<PlanetKitConferencePeer>) {
        // 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 events are generated:

  • Presenter: onMyScreenShareStoppedByHold
  • Peers: onScreenShareUpdated of ConferenceListener, onScreenShareUpdated of PeerControlListener (DISABLED state)

For group calls, the scope of the screen share determines the peers who receive the events, as follows:

  • If the screen share is targeted for the main room, all peers in the room receive the events.
  • If the screen share is targeted for a subgroup, only the peers who subscribed to the subgroup receive the events.

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

1-to-1 call​

Methods​

Events​

Group call​

Methods​

Events​