postTransferCall.md

{% method %}

Transfer active Call

Transfer a call to another phone number. This is a subset of update calls.

The call to be transferred must have state set to: active

Request URL

POSThttps://api.catapult.inetwork.com/v1/users/{userId}/calls/{callId}

---

Ensure call is active

To answer a call (or set to active) be sure to do one of the following:

• All incoming calls to be auto-answered. Set {"autoAnswer": true} flag in your application.
• Update the individual Call by: POST to the {callId} with {"state": "active"}.

Supported Parameters

Parameter	Description	Mandatory
state	transferring to transfer the incoming call to another line. The Call must be active	Yes
recordingEnabled	Indicates if the call should be recorded. Values true or false. You can turn recording on/off and have multiple recordings on a single call.	No
recordingFileFormat	The file format of the recorded call. Supported values are wav (default) and mp3.	No
transferTo	Phone number or SIP address that the call is going to be transferred to.	No
transferCallerId	This is the caller id that will be used when the call is transferred. This parameter is only considered in transfer state. - transferring an incoming call: allowed values are 1) private 2) the incoming call from number or 3) any Bandwidth number owned by user. - transferring an outgoing call call: allowed values are 1) private or 2) any Bandwidth phone number owned by user.	No
callbackUrl	The server URL where the call events for the new call will be sent upon transferring.	No
whisperAudio	Audio to be played to the caller that the call will be transferred to. See Audio Parameters below.	No
diversionTreatment	Can be any of the following: none: This is the default value. No Diversion headers are sent on the outbound leg of the transferred call. propagate: Copy the Diversion header from the inbound leg to the outbound leg. Ignored if there is no Diversion header present on the inbound leg. stack: After propagating any Diversion header from the inbound leg to the outbound leg, stack on top another Diversion header based on the Request-URI of the inbound call. If diversionTreatment is not specified, no diversion header will be included for the transfer even if one came with the inbound call.	No
diversionReason	Can be any of the following values: unknown user-busy no-answer unavailable unconditional time-of-day do-not-disturb deflection follow-me out-of-service away This parameter is considered only when diversionTreatment is set to stack.	No. Default to unknown.

Audio Parameters

Parameter	Description	Mandatory
fileUrl	The location of an audio file to play (WAV and MP3 supported).	No
sentence	The sentence to speak.	No
gender	The gender of the voice used to synthesize the sentence. It will be considered only if sentence is not null. The female gender will be used by default.	No
locale	The locale used to get the accent of the voice used to synthesize the sentence. Currently audio supports: - en_US or en_UK (English) - es or es_MX (Spanish) - fr or fr_FR (French) - de or de_DE (German) - t or it_IT (Italian) It will be considered only if sentence is not null/empty. The en_US will be used by default.	No
voice	The voice to speak the sentence. Audio currently supports the following voices: - English US: Kate, Susan, Julie, Dave, Paul - English UK: Bridget - Spanish: Esperanza, Violeta, Jorge - French: Jolie, Bernard - German: Katrin, Stefan - Italian: Paola, Luca It will be considered only if sentence is not null/empty. Susan’s voice will be used by default.	No

{% common %}

Example 1 of 3: Transfer a call using the caller Id of the party being transferred

{% sample lang="bash" %}

curl -v -X POST https://api.catapult.inetwork.com/v1/users/{userId}/calls/{callId} -u {token}:{secret} -H "Content-type: application/json" -d 
    '
	{
		"state"     : "transferring",
		"transferTo : "+19192223333"
	}
    '

{% sample lang="js" %}

var transferPayload = {
	transferTo       : "+18382947878",
};
//Using Promises
client.Call.transfer("callId", transferPayload).then(function (res) {});

{% sample lang="csharp" %}

await client.Call.TransferAsync("callID", "+18382947878");

{% sample lang="ruby" %}

call.update({:state => 'transferring', :transfer_to => '+18382947878' })

{% common %}

Example 2 of 3: Transfer a call and play audio to the '838-294-7878' Line

{% sample lang="bash" %}

curl -v -X POST https://api.catapult.inetwork.com/v1/users/{userId}/calls/{callId}	-u {token}:{secret} 	-H "Content-type: application/json" 	-d 	'
	{
		"state":"transferring",
		"transferCallerId": "private"
		"transferTo": "+18382947878",
		"whisperAudio": {
			"sentence" : "Hello! You have an incoming call"
		}
	}'

{% sample lang="js" %}

//Transfer call
var speakSentence = {
	transferTo       : "+18382947878",
	transferCallerId : "private",
	whisperAudio     : {
		sentence : "You have an incoming call",
		gender   : "female",
		voice    : "julie",
		locale   : "en"
	}
};

//Using Promises
client.Call.transfer("callId", speakSentence).then(function (res) {});

{% sample lang="csharp" %}

await client.Call.TransferAsync("callID", "+18382947878", "private", new WhisperAudio {
	Sentence = "You have an incoming call",
	Gender = "female",
	Voice = "julie",
	Locale = "en"
});

{% sample lang="ruby" %}

call.update({
	:state => 'transferring',
	:transfer_to => '+18382947878',
	:transfer_caller_id => 'private',
	:whisper_audio => {
		:sentence => 'You have an incoming call',
		:gender => 'female',
		:voice => 'julie',
		:locale => 'en'
	}
})

{% common %}

Example 3 of 3: Transfer with outbound Diversion header information

{% sample lang="bash" %}

curl -v -X POST https://api.catapult.inetwork.com/v1/users/{userId}/calls/{callId} -u {token}:{secret} -H "Content-type: application/json" -d
    '
    {
        "state":"transferring",
        "transferTo":"+19195554444",
        "diversionTreatment": "stack",
        "diversionReason":"do-not-disturb"
	}
    '

{% sample lang="js" %}

Coming soon

{% sample lang="csharp" %}

Coming soon

{% sample lang="ruby" %}

Coming soon

{% endmethod %}