In Twilio voice application development, putting the call on hold and subsequent recovery is a common requirement. However, direct update operations on a single call leg, such as modifying its TwiML URL, often lead to unexpected disconnection of calls from the other party. This is because when a TwiML instruction for a calling leg is executed or redirected, Twilio will consider that the current process for that leg is finished. This article will introduce two ways to enable call retention and recovery: using Twilio conferencing features (recommended) and handling independent call legs.

Method 1: Use Twilio Conference (recommended)

The Twilio conferencing feature is the easiest and most robust way to keep calls and recover. A meeting is essentially a virtual room that connects multiple participants together. In this mode, you can independently control the status of each participant in the meeting, including putting it in a hold state.

1. Put participants on hold

When a call leg joins a meeting as a participant, you can put it on hold by updating that participant’s resources. This involves sending an update request to the Twilio API, setting the hold property of the participant to True, and specifying a holdUrl to play the hold music.

Sample Code (PHP):

 <?php // Assume that you have installed the Twilio PHP library require_once &#39;vendor/autoload.php&#39; through Composer;

use Twilio\Rest\Client;

// Your Twilio Account SID and Auth Token
$sid = "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"; // 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 = "CFXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX; // Your meeting SID
$participantSid = "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX; // Participant SID to maintain

try {
    $participant = $client
        ->conferences($conferenceSid)
        ->participants($participantSid)
        ->update([
            "hold" => true,
            "holdUrl" => "http://www.myapp.com/hold_music.mp3" // Keep the URL of the music
        ]);

    echo "Participant" . $participant->callSid . " Successfully placed in hold state.\n";
} catch (Exception $e) {
    echo "An error occurred while putting participants in hold state: " . $e->getMessage() . "\n";
}
?>

In the above code, when hold is set to true, Twilio will play the audio specified by holdUrl to the participant, and other meeting participants will not be able to hear the participant.

2. Resuming the call

To restore a participant from keep to the meeting, simply update the participant's resource again and set the hold property to False.

Sample Code (PHP):

 <?php // Assume that you have installed the Twilio PHP library require_once &#39;vendor/autoload.php&#39; through Composer;

use Twilio\Rest\Client;

// Your Twilio Account SID and Auth Token
$sid = "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"; // 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 = "CFXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX; // Your meeting SID
$participantSid = "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX; // Participant SID to be restored

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

    echo "Participant" . $participant->callSid . "Recovered successfully from hold.\n";
} catch (Exception $e) {
    echo "An error occurred while recovering participants: " . $e->getMessage() . "\n";
}
?>

Notes:

• Use the meeting feature to simplify state management because Twilio handles the connection logic inside the meeting.
• holdUrl can be any accessible audio file URL, supporting MP3 and WAV formats.

Method 2: Handle independent call legs (advanced)

If you choose not to use the meeting feature, but instead directly manage two separate call legs, it will be more complicated to achieve call keeping. This is because when you update the TwiML of one call leg (for example, redirecting it to one hold TwiML), the current TwiML instruction of another call leg continues to execute and once executed, the call leg hangs up.

1. Understand the question: Why does the other party break?

The scenario described in the original question, that is, "when the calling party is maintained, the calling party is disconnected", is an embodiment of this mechanism. When you update a call via the API (for example, pointing its TwiML to a URL that plays and holds music), the TwiML stream of that call leg is interrupted and points to the new URL. Another call leg connected to it, its TwiML instruction (usually ) will assume that its connection target has been "completed", causing the TwiML process of that leg to continue execution, and will automatically hang up if there are no other instructions in the future.

Original code snippet analysis:

 // ...
$rr = array(
  "url" => "http://demo.twilio.com/docs/voice.xml", // New TwiML URL
  "method" => "POST"
);
$call = $client->calls($callSid)->update($rr); // Update the caller// ...

This code updates the TwiML source of the call leg represented by $callSid to http://demo.twilio.com/docs/voice.xml. If $callSid is the calling party and it was previously connected to the calling party through , then when the calling party's TwiML is updated, the instruction executed by the calling party will consider its connection "completed", and the calling party's TwiML will continue to be executed (if there is a subsequent one), otherwise it will hang up.

2. Provide follow-up TwiML for non-retaining legs

To avoid the non-holding leg disconnecting when the caller is held, you need to provide follow-up instructions in its TwiML. For example, add after the directive to get the call to another URL:

Example TwiML:

 <response>
  <dial> CUSTOMER_NUMBER</dial> <!-- Connect to the customer-->
  <redirect>https://example.com/hold_waiting</redirect> <!-- If Dial is finished, redirect to the waiting page-->
</response>

In this example, when the operation is completed (e.g., because the other leg is held or redirected), the call will not hang up, but will redirect to TwiML provided by https://example.com/hold_waiting. This TwiML can play a prompt tone to inform the user that they are waiting.

3. Implement a strategy for keeping and restoring

To achieve complete retention and recovery, the following strategies can be adopted:

• Keep it in action:

  • Update the TwiML of the call legs (e.g., agent legs) that need to be kept via the API to play the TwiML URL of the keep music.
  • Update the TwiML of another call leg (for example, client leg) via the API to the TwiML URL that queues the call (). This way, the client's legs will not hang up, but will be in a waiting queue.

  Example TwiML for Enqueue:

   <response>
    <enqueue waiturl="http://www.myapp.com/wait_music.mp3">MyCustomerQueue</enqueue>
  </response>

• Recovery operation:

  • Update the TwiML of the agent's leg to the TwiML URL that connects to the client queue via the directive.
  • When the agent legs are dialed into the queue, Twilio will connect the agent legs to the client legs waiting in the queue.

  Example TwiML for Dialing Queue:

   <response>
    <dial><queue>MyCustomerQueue</queue></dial>
  </response>

Notes:

• This approach requires you to manually manage the state of the two call legs and the TwiML flow, with a significant increase in complexity.
• You need to make sure your application is able to track the current status and corresponding Call SID of each call leg.
• Error handling and edge cases (such as customers who don't wait in the queue) need to be carefully considered.

Summary and best practices

From the above two methods, it can be seen that using the Twilio conferencing function is the most recommended way to maintain and restore calls. It provides built-in state management and simplified APIs that greatly reduce development complexity.

• Preferred plan: Twilio meeting. If your use case allows meetings, be sure to select this scenario. It provides more powerful features (such as multiple participants, mute, kick out, etc.) and keeps and restores operations intuitive and easy to implement.
• Advanced Solution: Independent Call Legs. Consider manually managing independent call legs only if your application scenario has special restrictions and cannot use the meeting feature. This approach requires you to have a deep understanding of Twilio's TwiML streams and API calls, and requires more code to handle call status, reconnect logic, and error situations.

Regardless of the method you choose, it is crucial to understand how Twilio TwiML works and how the API affects call status. By rationally designing your TwiML and backend logic, you can build a robust and user-experience Twilio voice application.