MakeCall

MakeCall
Prev	Actions	Next

Metreos.CallControl.MakeCall

Provider
Asynchronous
No Custom Parameters

Asynchronous Callbacks

Summary

Places an outbound call from the application server to a specified destination.

Usage

MakeCall will place a call to the destination specified by To. The resulting call leg, if completed, is a VOIP 'bridge' between the application server and the endpoint which answered the call, which could be a phone, voicemail, or another application. The practical use of MakeCall is to establish a call and media connection with a remote endpoint, essentially bringing a script into a telephony conversation and opening up the ability to utilize the other actions and events in the Call Control and Media Control APIs.

The application has little control over where the call is routed beyond the application server. See Call Routing for more information on how the application server interfaces with the outside world for the routing of calls.

The CallId result data parameter is the unique identifier for this call. All Call Control API actions and events use CallId, so practically the application developers almost always stores this CallId value in a variable for the use in subsequent Call Control operations. This CallId should not be considered unique across multiple application servers.

Once a call is placed with MakeCall, it will either eventually complete with the MakeCall_Complete event, meaning the call is answered and audio is flowing, or the call will fail with the MakeCall_Failed event, meaning the call is over (and the CallId for the call is no longer valid). There are a number of reasons why a call can fail to establish. When a calls fails to complete, the MakeCall_Failed event fires, with an EndReason event parameter indicating why the call failed.

As soon as a call is made, a number of unsolicited events can potentially occur, based on activity occurring in the call. These are GotDigits, RemoteHangup, StartTx, StopTx, and StartRx.

One can abort a 'ringing' call not yet established (a call is established, or completed, when the MakeCall_Complete event occurs) by using Hangup. To do so, supply to the Hangup action the CallId value returned as result data of the MakeCall action.

Remarks

An audio connection between the called destination and media engine is created automatically when one uses MakeCall, except for calls that are designated as peer-to-Peer by the PeerCallId action parameter. The application server automatically uses ReserveConnection and CreateConnection while the call is being established with the remote endpoint, with the end result of a valid ConnectionId being made available in the resulting MakeCall_Complete. This ConnectionId can then be used by the Media Control API.

When the call is hung up by either party, the ConnectionId is destroyed automatically by the application server.

The script does not have direct control over which telephony protocol is when placing the call, or which Cisco Unified Communications Manager is used to send the call to. The protocol used, and the Cisco Unified Communications Manager that is signalled when making the call, is determined by the configured Call Route Group on the current application partition.

The script does not have direct control over which media engine is used when placing the call, unless MmsId is specified. In the case that MmsId is not specified, the media engine used to process the audio connection is determined by the current Media Resource Group on the current application partition.

The Call Control API makes every effort to abstract the complexities of the underlying telephony protocol; however, one should consult the Call Control Feature Matrix to understand what Call Control actions and action parameters are valid for each of the four supported protocols. One can set installation and deployment guidelines based on the Call Control actions and action parameters that an application uses; the Call Control Feature Matrix makes developing such guidelines feasible.

The Reserve Media Early configuration on the script instance partition specifies whether a media engine connection should be provisioned with ReserveConnection as soon as the call is initiated, or if the application server should wait to until the media negotiation phase of the call ensues before reserving the connection. The media negotiation phase often comes as the call is answered by the remote endpoint, but can also come before the call is answered as well.

Action Parameters
Parameter Name	.NET Type	Description
To *	`System.String`	The destination number for this call. In practice, this number must be routable according to the dial plan of the Cisco Unified Communications Manager cluster that the call is sent to. All telephony protocols support this field.
From	`System.String`	The calling number, or 'caller ID', to present for this call. Not all telephony protocols support this field; please consult the Call Control Feature Matrix.
DisplayName	`System.String`	A free string which describes the initiator of the call. Not all telephony protocols support this field; please consult the Call Control Feature Matrix.
MmsId	`System.UInt32`	The ID of the media engine to create the connection on. If no MmsId is specified when using `MakeCall`, a media engine with the most available resources is dynamically selected from the Media Resource Group associated with the partition of the script instance from which `MakeCall` is invoked.
PeerCallId	`System.String`	The `CallId` of an unanswered incoming call that has triggered a script instance via the `IncomingCall` event. Once the call placed by this `MakeCall` is completed, the call specified by this action parameter is automatically answered by the application server and the media streams are established in a peer-to-peer relationship.
ProxyDTMFCallId	`System.String`	The `CallId` to establish a proxy relationship with. Any digits received on one call leg will be proxied to the other. If `ProxyDTMFCallId` is not set and `PeerCallId` is, then the call specified by `PeerCallId` will be used for this action parameter.
WaitForMedia	`System.String`	Indicates what degree of media negotiation must be established before the call is considered completed. A completed call results in the `MakeCall_Complete` event being fired. Valid values are as follows: None Indicates that the call should be considered completed as soon as the call control signaling has indicated that the call is answered, regardless of the state of media negotiation. Tx Indicates that the call should be considered completed as soon as the call control signaling has indicated that the call is answered and the remote endpoint has specified the properties of the audio stream that it wants transmitted to it. Rx Indicates that the call should be considered completed as soon as the call control signaling has indicated that the call is answered and the application server has specified the properties of the audio stream that it wants transmitted to the media engine. TxRx Indicates that the call should be considered completed as soon as the call control signaling has indicated that the call is answered, the remote endpoint has specified the properties of the audio stream that it wants transmitted to it, and the application server has specified the properties of the audio stream that it wants transmitted to the media engine. Note that depending on the value chosen, `MakeCall_Complete` event parameters relating to the negotiated media information may not be valid yet because the media negotiation may not yet be completed.
Conference	`System.Boolean`	Indicates that this call is to be placed in a conference. If a `ConferenceId` is not specified or is set to `0`, then a new conference is created on the media engine and the `ConferenceId` in the `MakeCall_Complete` event is the unique identifier for that new conference (assuming `WaitForMedia` is the default `TxRx`). If a `ConferenceId` is specified, then the connection created for this call is moved into the existing conference as soon as the media channels for the call have been fully established.
ConferenceId	`System.String`	The `ConferenceId` of the conference to add this call to. Specify no value or `0` if this is to be a new conference. This field is ignored if `Conference` is `false`.
Hairpin	`System.Boolean`	Indicates that the new conference should be optimized for two parties. A hairpinned conference does not use any conference resources. However, a hairpin conference will be 'promoted', or converted to a true media conference, if a 3rd participant is added to the conference or if a voice operation is performed on the conference itself. In either case, this will cause each participant and conferenced voice operation to use one conference resource. True conferences also have a slightly increased latency over a hairpinned conference.
Timeout	`System.Int32`	The `Timeout` property specifies to the `Application Runtime Environment` how long to wait for a response from the provider for the current action. The ReturnValue returned in this case is 'Timeout'. The value must be a literal value in milliseconds.

Result Data
Parameter Name	.NET Type	Description
CallId	`System.String`	Unique identifier used to identify this call in all subsequent Call Control API operations. This is the same value that will be returned as the event parameter `CallId` in the `MakeCall_Complete` event or in the `MakeCall_Failed` event.

Branch Conditions

Success: No description.
Failure: No description.
Timeout: No description.