Overview of Twilio Call Holding Mechanism

In Twilio, changing its target URL directly by updating a single call leg (Call SID) often causes the other party to be accidentally hanged up. This is because Twilio treats this update by default as the end of the route for that call leg, and the other party no longer has a connection target. In order to achieve call-holding function, that is, when one party is held and the other party can still stay connected or wait, we need to adopt a more advanced strategy. Twilio offers two main ways to solve this problem: leverage meeting features and managing independent call legs.

Method 1: Use Twilio meeting function to achieve call maintenance and recovery (recommended)

Using the Twilio Conference feature is the easiest and most recommended way to keep and restore calls. The conference function naturally supports multi-party call management, including maintenance operations for specific participants.

1. Putting a Call on Hold

When a party in the call is a meeting participant, it can be placed in a hold state by updating the participant's resources. This requires specifying the hold parameter to True and providing a holdUrl to play the hold music or prompt tone.

Implementation steps:

• Make sure your call participants are joining a Twilio meeting.
• Update the API of the Participant via the Twilio SDK.
• Set the hold parameter to True.
• Set the holdUrl parameter to point to a TwiML URL that returns the or directive used to play music or message.

Sample Code (PHP):

 <?php // Assume that the Twilio SDK has been introduced through Composer
require_once &#39;vendor/autoload.php&#39;;

use Twilio\Rest\Client;

// Your Twilio Account SID and Auth Token
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX; // Replace with your Account SID
$token = "your_auth_token"; // Replace with your Auth Token
$client = new Client($sid, $token);

// Suppose you already have a conference SID and a participant SID
$conferenceSid = "CFXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX; // Replace with your meeting SID
$participantSid = "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX; // Replace with the participant SID to be maintained

try {
    $participant = $client
        ->conferences($conferenceSid)
        ->participants($participantSid)
        ->update([
            "hold" => true,
            "holdUrl" => "http://www.myapp.com/hold_music.xml" // Replace with your Keep Music TwiML URL
        ]);

    echo "Participant" . $participant->callSid . " has been maintained.\n";
} catch (Exception $e) {
    echo "Stay call failed: " . $e->getMessage() . "\n";
}

// Example hold_music.xml content (located at http://www.myapp.com/hold_music.xml)
/*
<response>
  <play loop="0">http://demo.twilio.com/docs/voice.xml</play> // Play sample music</response>
*/
?>

Notes:

• holdUrl must return a valid TwiML, usually including or directives to provide a hold experience.
• Twilio automatically handles removing participants from the main audio stream of the meeting and connecting them to the audio stream specified by holdUrl.

2. Unholding a Call

To restore a call from hold, simply update the meeting participant again and set the hold parameter to False.

Implementation steps:

• Update the API of the Participant via the Twilio SDK.
• Set the hold parameter to False.

Sample Code (PHP):

 <?php // ... (The same initialization code as the above keep the call) ...

try {
    $participant = $client
        ->conferences($conferenceSid)
        ->participants($participantSid)
        ->update([
            "hold" => false
        ]);

    echo "Participant" . $participant->callSid . " Call resumed.\n";
} catch (Exception $e) {
    echo "Resuming call failed: " . $e->getMessage() . "\n";
}
?>

advantage:

• Easy to use: Twilio automatically handles keeping switches and audio stream routing.
• Powerful: The conference function itself supports advanced operations such as recording, muting, and removing participants.
• Good scalability: suitable for multi-party call scenarios.

Method 2: Manage independent call legs to achieve call retention (advanced TwiML method)

If your application scenario is not suitable for meeting features, or requires finer control of each call leg, you can manage the retention of the independent call leg through TwiML instructions. However, this approach is much more complex than using conference features, requiring developers to manually handle the routing and reconnection logic of the call legs.

1. Challenges and Principles

When you update a calling leg directly (for example, redirecting leg A to keep music), the other leg connected to leg A (Letter B) will hang up because of the completion of leg A's . To avoid this, it is necessary to ensure that leg B still has subsequent TwiML instructions to keep it active after leg A is maintained.

Sample TwiML structure:

 <response>
  <dial> CUSTOMER_NUMBER</dial> <!-- Initial Dial-->
  <redirect>https://example.com/hold_for_other_leg</redirect> <!-- If Dial is finished, where does B leg go -->
</response>

In the above TwiML, if the corresponding call leg of CUSTOMER_NUMBER is maintained (for example, by updating its TwiML to keep music), the action will be completed and the call flow will continue to be executed at https://example.com/hold_for_other_leg. The TwiML returned by this URL should keep the B leg active, such as playing and waiting for music.

2. To implement a call on Hold

For independent call legs, a more robust way is to use to place the call legs into a queue.

Implementation steps:

• For the held call leg (for example, A leg): Update its TwiML URL to return the directive, putting the A leg into a specific queue (for example, "HoldQueue").
• For call legs that remain connected (for example, leg B): Ensure that its TwiML process does not cause hangup after leg A is maintained. Usually, this requires leg B to enter a waiting state, such as playing waiting music, or also entering a queue.

Example TwiML (for call leg A that is held):

 <!-- When it is necessary to keep call leg A, update its Call URL pointing to this TwiML -->
<response>
  <enqueue waiturl="http://www.myapp.com/hold_music_for_queue.xml">HoldQueue</enqueue>
</response>

3. Unholding a Call

Resuming calls to independent call legs means that the two call legs need to be reconnected. If is used, the recovery operation usually involves getting the other leg into the same queue.

Implementation steps:

• For call leg that remains connected (for example, B leg): Update its TwiML URL to return the directive and specify the name so that leg B is connected to the A leg waiting in the queue.

Example TwiML (for restoring call leg B):

 <!-- When a call needs to be resumed, update call leg B&#39;s Call URL point to this TwiML -->
<response>
  <dial><queue>HoldQueue</queue></dial>
</response>

When B leg dials in "HoldQueue", Twilio will automatically connect B leg to the A leg waiting in the queue, thereby achieving call recovery.

Notes:

• This approach requires more complex logic to manage the state and routing of each call leg.
• The TwiML process needs to be carefully designed to ensure that all call legs can enter and exit the corresponding state correctly during the retention and recovery process.
• Error handling and exceptions (such as the queue is empty) require additional logic to handle.

Summary and suggestions

• It is highly recommended to use the Twilio Conference feature to enable call retention and recovery. It provides a simple API interface and built-in functions such as music preservation and participant management, which greatly reduces development complexity. For most scenarios where call-holding functionality is required, the meeting feature is the best choice.
• The independent call leg management method is suitable for special and complex scenarios. If you need extreme control over the life cycle and routing of each call leg, and the meeting functionality does not meet your specific needs, consider using a combination of and . But be aware that this will increase the logic complexity of your application.
• Whichever method you choose, providing high-quality keeping music or cushion sounds (via holdUrl or waitUrl) is essential to enhance the user experience.

Choosing the right strategy depends on your specific needs and how accepting complexity is. For typical customer service or transfer scenarios, the meeting function is undoubtedly a more efficient and reliable solution.