Update Call - Live Call Control
This api allows you to manipulate a call that is in progress — i.e., “Live Call Control”.
The actions available are:
- hangup a call
- mute/unmute a party on a call
- pause/resume the real-time audio stream provided via the listen command
- transfer one or both parties on a call to new application(s). Note that you can provide a different application for each party (e.g. queue the called party while the calling party dials a new number)
- play a whisper prompt to a party.
- place or remove a party that is in conference on hold.
- mute/unmute all non-moderators in a conference.
Generally, a single API call can only do one of the above operations.
The JSON payload may contain the properties described in the table below.
| property | description | when can this be used |
|---|---|---|
| call_hook | a new application to start executing on the call for the party associated with the call_sid | at any time a call is active |
| child_call_hook | a new application to start executing on the call for the party associated with the child_call_sid | at any time a call is active and in a dial verb |
| call_status | Change the status of the call. Possible values are ‘completed’ or ‘no-answer’ (the former terminates an answered call, the latter a call that is ringing) | at any time a call is in-progress or ringing |
| conf_hold_status | Possible values are ‘hold’ or ‘unhold’. When playing a party on hold, a wait_hook can optionally be provided to play music or a message to the party while on hold. | Only valid when the party is in a conference. |
| conf_mute_status | Possible values are ‘mute’ or ‘unmute’. Note that this action applies to all non-morderators in the conference, not to a single member | Only valid when the party is in a conference. |
| listen_status | Change the status of a listen stream. Possible values are ‘pause’ or ‘resume’. Pausing a stream maintains the websocket connection but will discontinue sending audio over the connection. Resuming will start sending audio again. This may be useful, for example, when a caller is providing confidential information that you do not want to appear in a recording. | only when a listen command is active on the call (may be nested in an active dial command) |
| mute_status | Mute or unmute a call that is currently in a Dial verb. Possible values are ‘mute’ or ‘unmute’. Either party in a call may be modified, depending on the call_sid provided in the path of the request-uri. | only when a dial command is currently active on a call |
| whisper | Play a mid-call whisper prompt to one of the parties on a call in progress. The whisper prompt is provided in a play or say verb, as shown in the examples below. The whisper may be played to either party on the call, depending on the call_sid provided in the path of the request-uri. The other party is briefly placed on hold while the prompt is played, and then reconnected to the other party afterwards. | only when a dial command is currently active on the call |
| wait_hook | A relative or absolute url that can be supplied when placing a party that is in conference on hold. | Only when putting a party on conference hold |
The call_status, listen_status, and mute_status properties are mutually exclusive — only one may be provided in the same request.
The whisper property may be provided alone, or together with a listen_status or mute_status property, in which case the whisper prompt is played after the listen_status or mute_status operation is complete.
Finally, if call_hook is provided, then call_status_hook may also optionally be included. This is used to specify a new callback to receive call status events.
Success is indicated by a 204 response
Update Call - Live Call Control
This api allows you to manipulate a call that is in progress — i.e., “Live Call Control”.
The actions available are:
- hangup a call
- mute/unmute a party on a call
- pause/resume the real-time audio stream provided via the listen command
- transfer one or both parties on a call to new application(s). Note that you can provide a different application for each party (e.g. queue the called party while the calling party dials a new number)
- play a whisper prompt to a party.
- place or remove a party that is in conference on hold.
- mute/unmute all non-moderators in a conference.
Generally, a single API call can only do one of the above operations.
The JSON payload may contain the properties described in the table below.
| property | description | when can this be used |
|---|---|---|
| call_hook | a new application to start executing on the call for the party associated with the call_sid | at any time a call is active |
| child_call_hook | a new application to start executing on the call for the party associated with the child_call_sid | at any time a call is active and in a dial verb |
| call_status | Change the status of the call. Possible values are ‘completed’ or ‘no-answer’ (the former terminates an answered call, the latter a call that is ringing) | at any time a call is in-progress or ringing |
| conf_hold_status | Possible values are ‘hold’ or ‘unhold’. When playing a party on hold, a wait_hook can optionally be provided to play music or a message to the party while on hold. | Only valid when the party is in a conference. |
| conf_mute_status | Possible values are ‘mute’ or ‘unmute’. Note that this action applies to all non-morderators in the conference, not to a single member | Only valid when the party is in a conference. |
| listen_status | Change the status of a listen stream. Possible values are ‘pause’ or ‘resume’. Pausing a stream maintains the websocket connection but will discontinue sending audio over the connection. Resuming will start sending audio again. This may be useful, for example, when a caller is providing confidential information that you do not want to appear in a recording. | only when a listen command is active on the call (may be nested in an active dial command) |
| mute_status | Mute or unmute a call that is currently in a Dial verb. Possible values are ‘mute’ or ‘unmute’. Either party in a call may be modified, depending on the call_sid provided in the path of the request-uri. | only when a dial command is currently active on a call |
| whisper | Play a mid-call whisper prompt to one of the parties on a call in progress. The whisper prompt is provided in a play or say verb, as shown in the examples below. The whisper may be played to either party on the call, depending on the call_sid provided in the path of the request-uri. The other party is briefly placed on hold while the prompt is played, and then reconnected to the other party afterwards. | only when a dial command is currently active on the call |
| wait_hook | A relative or absolute url that can be supplied when placing a party that is in conference on hold. | Only when putting a party on conference hold |
The call_status, listen_status, and mute_status properties are mutually exclusive — only one may be provided in the same request.
The whisper property may be provided alone, or together with a listen_status or mute_status property, in which case the whisper prompt is played after the listen_status or mute_status operation is complete.
Finally, if call_hook is provided, then call_status_hook may also optionally be included. This is used to specify a new callback to receive call status events.
Success is indicated by a 204 response