Hold

During a programmable SIP call, the RCML <Hold> Verb instructs Restcomm to put the remote party on hold with silence or music on hold.Calls wait on hold until the call is resumed via the <Resume> verb. Calls wait on hold until the call is resumed via the <Resume> verb.

The <Hold> feature can be invoked via REST API as well.

Hold Attributes

Name	Allowed Values	Default Value
action	relative or absolute URL	none
method	GET, POST	POST
holdMusic	absolute URL	none

Name

Allowed Values

Default Value

action

relative or absolute URL

none

method

GET, POST

POST

holdMusic

absolute URL

none

Action Attribute

The 'action' attribute takes a URL as an argument.

After Hold executes, Restcomm will make a GET or POST request to this URL including the parameters below.

If you provide an 'action' URL, Restcomm will continue the current call after the hold finished, using the RCML received in your response to the 'action' URL request.

Any RCML verbs occuring after a <Hold> which specifies an 'action' attribute are unreachable.

If no 'action' is provided, <Hold> will finish and Restcomm will move on to the next RCML verb in the document.

If there is no next verb, Restcomm will end the phone call.

Method Attribute

The 'method' attribute takes the value 'GET' or 'POST'.

This tells Restcomm whether to request the URL via HTTP GET or POST.

HoldMusic Attribute

The 'holdMusic' attribute lets you specify a custom music file to be played while the caller is on Hold.

The file will be played in a loop until the call is resumed or modified through Live Call Modification.

The attribute value is a valid URL pointing to WAV file.

Hold Action Parameters

The Restcomm parameters passed to your application in its asynchronous request to the Hold action URL. The list of basic parameters can be found in the RCML Voice Request documentation.

The <Hold> request also passes these additional parameters:

Parameter	Description	Allowed Values
HoldStatus	Provides the application with our understanding (based on SIP re-INVITE transaction messages) of the status of the Hold.	held, failed, no-answer
HoldSipResponseCode	The SIP response code received in response to the HOLD request sent to the SIP endpoint.	integer

Parameter

Description

Allowed Values

HoldStatus

Provides the application with our understanding (based on SIP re-INVITE transaction messages) of the status of the Hold.

held, failed, no-answer

HoldSipResponseCode

The SIP response code received in response to the HOLD request sent to the SIP endpoint.

integer

Notice that Restcomm will also send the standard RCML Voice parameters in the request.

Nesting

<Hold> does not support nesting.

Examples

For examples of how to use the <Hold> verb see below.

Hold a call leg and perform an action when finished

<Response>
   <Hold action="/myHoldAction" method="POST"/>
</Response>

Hold Call Flows

The following flow diagrams illustrate the possible call flow scenarios for the RCML <Hold> verb.

Successful Hold

The diagram below outlines dialing to a Restcomm IVR. After the subscriber press a digit, call is held to the destination subscriber.