Skip to main content

Relay.Calling.Call

All calls in SignalWire have a common generic interface, Call. A Call is a connection between SignalWire and another device.

Properties

idstringThe unique identifier of the call.
typestringThe type of call. Only phone is currently supported.
fromstringThe phone number that the call is coming from.
tostringThe phone number you are attempting to call.
timeoutnumberThe seconds the call rings before being transferred to voicemail.
statestringThe current state of the call. See Relay.Calling.Call State Events for all the possible call states.
prevStatestringThe previous state of the call.
contextstringThe context the call belongs to.
peerRelay.Calling.CallThe call your original call is connected to.
activebooleanWhether the call is active.
endedbooleanWhether the call has ended.
answeredbooleanWhether the call has been answered.
failedbooleanWhether the call has failed.
busybooleanWhether the call was busy.

Methods

amd

Alias for detectAnsweringMachine.

amdAsync

Alias for detectAnsweringMachineAsync.

answer

Answer an inbound call.

Available In:

Parameters

None

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.AnswerResult object.

Examples

Answer an inbound call and check if it was successful.
<?php

$call->answer()->done(function($answerResult) {

});

connect

Attempt to connect an existing call to a new outbound call and waits until one of the remote party picks the call or the connect fails.
This method involves complex nested parameters. You can connect to multiple devices in series, parallel, or any combination of both with creative use of the parameters. Series implies one device at a time, while parallel implies multiple devices at the same time.

Available In:

Parameters

$paramsarrayrequiredArray with the following properties:
devicesarrayrequiredOne or more arrays with the structure below.
Nested depends on whether to dial in serial or parallel.
ringbackarrayoptionalRingback audio to play to call leg. You can play audio, tts, silence or ringtone. See play media parameter for details.
  • Structure of a device:
typestringrequiredThe device type. Only phone is currently supported.
fromstringoptionalThe party the call is coming from.
If not provided, the SDK will use the from of the originator call.
Must be a SignalWire number or SIP endpoint that you own.
tostringrequiredThe party you are attempting to connect with.
timeoutnumberoptionalThe time, in seconds, the call will ring before going to voicemail.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.ConnectResult object.

Examples

Try connecting by calling '+18991114444' and '+18991114445' in series.
<?php

$devices = [
[ "type" => "phone", "to" => "+18991114444", "timeout" => 30 ],
[ "type" => "phone", "to" => "+18991114445", "timeout" => 20 ]
];
$call->connect(...$devices)->done(function($connectResult) {
if ($connectResult->isSuccessful()) {
$remoteCall = $connectResult->getCall();
}
});
Combine serial and parallel calling. Call '+18991114443' first and - if it doesn't answer - try calling in parallel '+18991114444' and '+18991114445'. If none of the devices answer, continue the same process with '+18991114446' and '+18991114447'.
<?php

$devices = [
[ "type" => "phone", "to" => "+18991114443", "timeout" => 30 ],
[
[ "type" => "phone", "to" => "+18991114444", "timeout" => 30 ],
[ "type" => "phone", "to" => "+18991114445", "timeout" => 20 ]
],
[
[ "type" => "phone", "to" => "+18991114446", "timeout" => 30 ],
[ "type" => "phone", "to" => "+18991114447", "timeout" => 20 ]
]
];
$call->connect(...$devices)->done(function($connectResult) {
if ($connectResult->isSuccessful()) {
$remoteCall = $connectResult->getCall();
}
});
Try connecting by calling '+18991114444' and '+18991114445' in series playing the US ringtone.
<?php

$params = [
"devices" => [
[ "type" => "phone", "to" => "+18991114444" ],
[ "type" => "phone", "to" => "+18991114445" ]
],
"ringback" => [ "type" => "ringtone", "name" => "us" ]
];
$call->connect(...$devices)->done(function($connectResult) {
if ($connectResult->isSuccessful()) {
$remoteCall = $connectResult->getCall();
}
});

connectAsync

Asynchronous version of connect. It does not wait the connect to completes or fails but returns a Relay.Calling.ConnectAction you can interact with.

Available In:

Parameters

See connect for the parameter list.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.ConnectAction object.

Examples

Trying to connect a call by calling in series '+18991114444' and '+18991114445'.
<?php

$devices = [
[ "type" => "phone", "to" => "+18991114444", "timeout" => 30 ],
[ "type" => "phone", "to" => "+18991114445", "timeout" => 20 ]
];
$call->connect(...$devices)->done(function($connectAction) {
// .. do other important things while Relay try to connect your call..

// then check whether the action has completed
if ($connectAction->isCompleted()) {

}
});

detect

Start a detector on the call and waits until it has finished or failed.

The detect method is a generic method for all types of detecting, see detectAnsweringMachine, detectDigit or detectFax for more specific usage.

Available In:

Parameters

$paramsarrayrequiredArray with the following properties:
  • To detect an answering machine:
typestringrequiredmachine
timeoutnumberoptionalNumber of seconds to run the detector.
Defaults to 30.0.
wait_for_beepbooleanoptionalWhether to wait until the AM is ready for voicemail delivery.
Defaults to false.
initial_timeoutnumberoptionalNumber of seconds to wait for initial voice before giving up.
Defaults to 4.5.
end_silence_timeoutnumberoptionalNumber of seconds to wait for voice to finish.
Defaults to 1.0.
machine_voice_thresholdnumberoptionalHow many seconds of voice to decide is a machine.
Defaults to 1.25.
machine_words_thresholdnumberoptionalHow many words to count to decide is a machine.
Defaults to 6.
  • To detect digits:
typestringrequireddigit
timeoutnumberoptionalNumber of seconds to run the detector.
Defaults to 30.0.
digitsstringoptionalThe digits to detect.
Defaults to "0123456789#*".
  • To detect a fax:
typestringrequiredfax
timeoutnumberoptionalNumber of seconds to run the detector.
Defaults to 30.0.
tonestringoptionalThe fax tone to detect: CED or CNG.
Defaults to "CED".

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.DetectResult object.

Examples

Detect a machine with custom parameters and timeout.
<?php

$params = [
'type' => 'machine',
'timeout' => 45,
'initial_timeout' => 3.0
];
$call->detect($params)->done(function($detectResult) {
if ($detectResult->isSuccessful()) {
$type = $detectResult->getType(); // machine
$result = $detectResult->getResult(); // MACHINE / HUMAN / UNKNOWN
}
});
Detect a Fax setting timeout only.
<?php

$params = [
'type' => 'fax',
'timeout' => 45
];
$call->detect($params)->done(function($detectResult) {
if ($detectResult->isSuccessful()) {

}
});

detectAsync

Asynchronous version of detect. It does not wait the detector ends but returns a Relay.Calling.DetectAction you can interact with.

Available In:

Parameters

See detect for the parameter list.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.DetectAction object.

Examples

Detect digits using default parameters. Stop the action immediately.
<?php

$call->on('detect.update', function ($call, $params) {
// Handle a detector event here..
print_r($params);
});
$call->detectAsync([ 'type' => 'digit' ])->done(function ($detectAction) {
// Do other things while detector runs and then stop it.
if (!$detectAction->isCompleted()) {
$detectAction->stop();
}
});

detectAnsweringMachine

This is a helper function that refines the use of detect. The Promise will be resolved with a Relay.Calling.DetectResult object as soon as the detector decided who answered the call: MACHINE, HUMAN or UNKNOWN.

Available In:

Parameters

$paramsarrayoptionalArray with the following properties:
timeoutnumberoptionalNumber of seconds to run the detector.
Defaults to 30.0.
wait_for_beepbooleanoptionalWhether to wait until the AM is ready for voicemail delivery.
Defaults to false.
initial_timeoutnumberoptionalNumber of seconds to wait for initial voice before giving up.
Defaults to 4.5.
end_silence_timeoutnumberoptionalNumber of seconds to wait for voice to finish.
Defaults to 1.0.
machine_voice_thresholdnumberoptionalHow many seconds of voice to decide is a machine.
Defaults to 1.25.
machine_words_thresholdnumberoptionalHow many words to count to decide is a machine.
Defaults to 6.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.DetectResult object.

Examples

Perform an AMD and wait until the machine is ready.
<?php

$params = [
'wait_for_beep' => true
];
$call->detectAnsweringMachine($params)->done(function($detectResult) {
if ($detectResult->isSuccessful()) {
$result = $detectResult->getResult(); // MACHINE || HUMAN || UNKNOWN
}
});

detectAnsweringMachineAsync

Asynchronous version of detectAnsweringMachine. It does not wait the detector ends but returns a Relay.Calling.DetectAction you can interact with.

Available In:

Parameters

See detectAnsweringMachine for the parameter list.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.DetectAction object.

Examples

Perform an asynchronous AMD on the call. Then stop the action if not completed yet.
<?php

$call->on('detect.update', function ($call, $params) {
// Handle a detector event here..
print_r($params);
});
$call->detectAnsweringMachineAsync()->done(function ($detectAction) {
// Do other things while detector runs and then stop it.
if (!$detectAction->isCompleted()) {
$detectAction->stop();
}
});

detectDigit

This is a helper function that refines the use of detect. This simplifies detecting digits on a call.

Available In:

Parameters

$paramsarrayoptionalArray with the following properties:
timeoutnumberoptionalNumber of seconds to run the detector.
Defaults to 30.0.
digitsstringoptionalThe digits to detect.
Defaults to "0123456789#*".

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.DetectResult object.

Examples

Detect digits and then write a log with the result.
<?php

$call->detectDigit()->done(function($detectResult) {
if ($detectResult->isSuccessful()) {
echo "Digits detected: " . $detectResult->getResult();
}
});

detectDigitAsync

Asynchronous version of detectDigit. It does not wait the detector ends but returns a Relay.Calling.DetectAction you can interact with.

Available In:

Parameters

See detectDigit for the parameter list.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.DetectAction object.

Examples

Detect only '1-3' digits asynchronously.
<?php

$call->on('detect.update', function ($call, $params) {
// Handle a detector event here..
print_r($params);
});
$call->detectDigitAsync([ 'digits' => '123' ])->done(function ($detectAction) {
// Do other things while detector runs and then stop it.
if (!$detectAction->isCompleted()) {
$detectAction->stop();
}
});

detectFax

This is a helper function that refines the use of detect. This simplifies detecting a fax.

Available In:

Parameters

$paramsarrayoptionalArray with the following properties:
timeoutnumberoptionalNumber of seconds to run the detector.
Defaults to 30.0.
tonestringoptionalThe fax tone to detect: CED or CNG.
Defaults to "CED".

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.DetectResult object.

Examples

Detect fax on the current call.
<?php

$call->detectFax()->done(function($detectResult) {
if ($detectResult->isSuccessful()) {
// A fax has been detected!
}
});

detectFaxAsync

Asynchronous version of detectFax. It does not wait the detector ends but returns a Relay.Calling.DetectAction you can interact with.

Available In:

Parameters

See detectFax for the parameter list.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.DetectAction object.

Examples

Detect fax on the current call. Stop the action immediately.
<?php

$call->on('detect.update', function ($call, $params) {
// Handle a detector event here..
print_r($params);
});
$call->detectFaxAsync()->done(function ($detectAction) {
// Do other things while detector runs and then stop it.
if (!$detectAction->isCompleted()) {
$detectAction->stop();
}
});

detectHuman

This is a helper function that refines the use of detect. This simplifies detecting a human on the call and is the inverse of detectMachine.

Deprecated since: Use detectAnsweringMachine instead.

Parameters

$paramsarrayoptionalArray with the following properties:
timeoutnumberoptionalNumber of seconds to run the detector.
Defaults to 30.0.
wait_for_beepbooleanoptionalWhether to wait until the AM is ready for voicemail delivery.
Defaults to false.
initial_timeoutnumberoptionalNumber of seconds to wait for initial voice before giving up.
Defaults to 4.5.
end_silence_timeoutnumberoptionalNumber of seconds to wait for voice to finish.
Defaults to 1.0.
machine_voice_thresholdnumberoptionalHow many seconds of voice to decide is a machine.
Defaults to 1.25.
machine_words_thresholdnumberoptionalHow many words to count to decide is a machine.
Defaults to 6.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.DetectResult object.

Examples

Detect a human on the current call.
<?php

$call->detectHuman()->done(function($detectResult) {
if ($detectResult->isSuccessful()) {
// A human has been detected!
}
});

detectHumanAsync

Asynchronous version of detectHuman. It does not wait the detector ends but returns a Relay.Calling.DetectAction you can interact with.

Deprecated since: Use detectAnsweringMachineAsync instead.

Parameters

See detectHuman for the parameter list.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.DetectAction object.

Examples

Detect a human on the current call. Stop the action immediately.
<?php

$call->detectHumanAsync()->done(function ($detectAction) {
// For demonstration purposes only..
$detectAction->stop();
});

detectMachine

This is a helper function that refines the use of detect. This simplifies detecting a machine on the call and is the inverse of detectHuman.

Deprecated since: Use detectAnsweringMachine instead.

Parameters

$paramsarrayoptionalArray with the following properties:
timeoutnumberoptionalNumber of seconds to run the detector.
Defaults to 30.0.
wait_for_beepbooleanoptionalWhether to wait until the AM is ready for voicemail delivery.
Defaults to false.
initial_timeoutnumberoptionalNumber of seconds to wait for initial voice before giving up.
Defaults to 4.5.
end_silence_timeoutnumberoptionalNumber of seconds to wait for voice to finish.
Defaults to 1.0.
machine_voice_thresholdnumberoptionalHow many seconds of voice to decide is a machine.
Defaults to 1.25.
machine_words_thresholdnumberoptionalHow many words to count to decide is a machine.
Defaults to 6.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.DetectResult object.

Examples

Detect a machine on the current call.
<?php

$call->detectMachine()->done(function($detectResult) {
if ($detectResult->isSuccessful()) {
// A machine has been detected!
}
});

detectMachineAsync

Asynchronous version of detectMachine. It does not wait the detector ends but returns a Relay.Calling.DetectAction you can interact with.

Deprecated since: Use detectAnsweringMachineAsync instead.

Parameters

See detectMachine for the parameter list.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.DetectAction object.

Examples

Detect a machine on the current call. Stop the action immediately.
<?php

$call->detectMachineAsync()->done(function ($detectAction) {
// For demonstration purposes only..
$detectAction->stop();
});

dial

This will start a call that was created with newCall and waits until the Call has been answered or hung up.

Available In:

Parameters

None

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.DialResult object.

Examples

<?php

$call->dial()->done(function($dialResult) {

});

faxReceive

Prepare the call to receive an inbound fax. It waits until the fax has been received or failed.

Available In:

Parameters

None

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.FaxResult object.

Examples

Receiving a fax on the call and print logs for URL and number of received pages.
<?php

$call->faxReceive()->done(function($faxResult) {
echo 'URL: ' . $faxResult->getDocument() . PHP_EOL;
echo 'Total pages: ' . $faxResult->getPages();
});

faxReceiveAsync

Asynchronous version of faxReceive. It does not wait the fax to be received but returns Relay.Calling.FaxAction you can interact with.

Available In:

Parameters

None

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.FaxAction object.

Examples

Trying to receive a fax and then stop it.
<?php

$call->faxReceiveAsync()->done(function ($faxAction) {
// For demonstration purposes only..
$faxAction->stop();
});

faxSend

Send a fax through the call. It waits until the fax has been sent or failed.

Available In:

Parameters

$documentstringrequiredHttp(s) URL to the document to send.
PDF format only.
$identitystringoptionalIdentity to display on receiving fax.
Defaults to SignalWire DID.
$headerstringoptionalCustom string to add to header of each fax page.
Set to empty string to disable sending any header.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.FaxResult object.

Examples

Sending a fax on the call and print logs the number of sent pages.
<?php

$call->faxSend('https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf', null, 'Custom Header')->done(function($faxResult) {
echo "\n URL: " . $faxResult->getDocument();
echo "\n Total pages: " . $faxResult->getPages();
});

faxSendAsync

Asynchronous version of faxSend. It does not wait the fax to be sent but returns a Relay.Calling.FaxAction you can interact with.

Available In:

Parameters

See faxSend for the parameter list.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.FaxAction object.

Examples

Trying to send a fax and then stop it.
<?php

$call->faxSendAsync('https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf', null, 'Custom Header')->done(function ($faxAction) {
// For demonstration purposes only..
$faxAction->stop();
});

hangup

Hangup the call.

Available In:

Parameters

None

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.HangupResult object.

Examples

Hangup the current call and check if it was successful.
<?php

$call->hangup()->done(function($hangupResult) {
if ($hangupResult->isSuccessful()) {

}
});

on

Attach an event handler for the event.

Available In:

Parameters

$eventstringrequiredEvent name. Full list of events Relay.Calling.Call Events
$handlercallablerequiredHandler to call when the event comes.

Returns

Relay.Calling.Call - The call object itself.

Examples

Subscribe to the 'answered' and 'ended' events for a given call.
<?php

$call->on('ended', function($call) {
// Call has ended.. cleanup something?
});

off

Remove an event handler that were attached with the on method. If you don't pass a $handler, all listeners for that event will be removed.

Available In:

Parameters

$eventstringrequiredEvent name. Full list of events Relay.Calling.Call Events
$handlercallableoptionalHandler to remove.
Note: $handler will be removed from the stack by reference so make sure to use the same reference in both on and off methods.

Returns

Relay.Calling.Call - The call object itself.

Examples

Subscribe to the call 'ended' state change and then, remove the event handler.
<?php

$callback = function($call) {
// Call has ended.
};

$call->on('ended', $callback);

// .. later
$call->off('ended', $callback);

play

Play one or multiple media in a call and waits until the playing has ended.

The play method is a generic method for all types of playing, see playAudio, playSilence, playTTS or playRingtone for more specific usage.

Available In:

Parameters

$paramsarrayrequiredArray with the following properties:
mediaarrayrequiredList of media elements to play. See below for each type.
volumenumberoptional Volume value between -40dB and +40dB where 0 is unchanged.
Default is 0.
  • To play an audio file:
typestringrequiredaudio
urlstringrequiredHttp(s) URL to audio resource to play.
  • To play a text to speech string:
typestringrequiredtts
textstringrequiredTTS to play.
languagestringoptionalDefault to en-US.
genderstringoptionalmale or female. Default to female.
  • To play silence:
typestringrequiredsilence
durationnumberrequiredSeconds of silence to play.
  • To play ringtone:
typestringrequiredringtone
namestringrequiredThe name of the ringtone. See ringtones for the supported values.
durationnumberoptionalDuration of ringtone to play.
Default to 1 ringtone iteration.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.PlayResult object.

Examples

Play multiple media elements in the call.
<?php

$params = [
'media' => [
[ "type" => "tts", "text" => "Listen this awesome file!" ],
[ "type" => "audio", "url" => "https://example.domain.com/audio.mp3" ],
[ "type" => "silence", "duration" => 5 ],
[ "type" => "tts", "text" => "Did you like it?" ]
],
'volume' => 4.0
];
$call->play($params)->done(function ($playResult) {
if ($playResult->isSuccessful()) {

}
});

playAsync

Asynchronous version of play. It does not wait the playing to completes but returns a Relay.Calling.PlayAction you can interact with.

Available In:

Parameters

See play for the parameter list.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.PlayAction object.

Examples

Play multiple media elements in the call and then stop it.
<?php

$params = [
'media' => [
[ "type" => "tts", "text" => "Listen this awesome file!" ],
[ "type" => "audio", "url" => "https://example.domain.com/audio.mp3" ],
[ "type" => "silence", "duration" => 5 ],
[ "type" => "tts", "text" => "Did you like it?" ]
],
'volume' => 4.0
];
$call->playAsync($params)->done(function ($playAction) {
// For demonstration purposes only..
$playAction->stop();
});

playAudio

This is a helper function that refines the use of play. This simplifies playing an audio file.

Available In:

Parameters

$paramsarrayrequiredArray with the following properties:
urlstringrequiredHttp(s) URL to audio resource to play.
volumenumberoptional Volume value between -40dB and +40dB where 0 is unchanged.
Default is 0.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.PlayResult object.

Examples

Play an Mp3 file using the signature with a 'string' as parameter.
<?php

$call->playAudio('https://cdn.signalwire.com/default-music/welcome.mp3')->done(function($playResult) {
// interact with $playResult..
});
Play an Mp3 file setting volume level to 4dB. Require v2.3+.
<?php

$params = [
'url' => 'https://cdn.signalwire.com/default-music/welcome.mp3',
'volume' => 4.0
];
$call->playAudio($params)->done(function($playResult) {
// interact with $playResult..
});

playAudioAsync

Asynchronous version of playAudio. It does not wait the playing to completes but returns a Relay.Calling.PlayAction you can interact with.

Available In:

Parameters

See playAudio for the parameter list.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.PlayAction object.

Examples

Play an Mp3 file and stop it after 5 seconds.
<?php

$call->playAudioAsync('https://cdn.signalwire.com/default-music/welcome.mp3')->done(function($playAction) {
// For demonstration purposes only..
$playAction->stop();
});
Play an Mp3 file setting the volume and stop it after 5 seconds.
<?php

$params = [
'url' => 'https://cdn.signalwire.com/default-music/welcome.mp3',
'volume' => 4.0
];
$call->playAudioAsync($params)->done(function($playAction) {
// For demonstration purposes only..
$playAction->stop();
});

playRingtone

This is a helper function that refines the use of play. This simplifies play a ringtone.

Available In:

Parameters

$paramsarrayrequiredArray with the following properties:
namestringrequiredThe name of the ringtone. See ringtones for the supported values.
durationnumberoptionalDuration of ringtone to play.
Default to 1 ringtone iteration.
volumenumberoptionalVolume value between -40dB and +40dB where 0 is unchanged.
Default is 0.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.PlayResult object.

Examples

Play a single US ringtone.
<?php

$params = [ 'name' => 'us' ];
$call->playRingtone($params)->done(function($playResult) {
// interact with $playResult..
});

playRingtoneAsync

Asynchronous version of playRingtone. It does not wait the playing to completes but returns a Relay.Calling.PlayAction you can interact with.

Available In:

Parameters

See playRingtone for the parameter list.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.PlayAction object.

Examples

Play US ringtone for 30 seconds, if 'Agent' is available, stop the play.
<?php

$params = [ 'name' => 'us', 'duration' => 30 ];
$call->playRingtoneAsync($params)->done(function($playAction) use ($globalAgent) {
// For demonstration purposes only ..
if ($globalAgent->isAvailable()) {
$playAction->stop();
}
});

playSilence

This is a helper function that refines the use of play. This simplifies playing silence.

Available In:

Parameters

$durationnumberrequiredSeconds of silence to play.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.PlayResult object.

Examples

Play silence for 10 seconds.
<?php

$call->playSilence(10)->done(function($playResult) {
// interact with $playResult..
});

playSilenceAsync

Asynchronous version of playSilence. It does not wait the playing to completes but returns a Relay.Calling.PlayAction you can interact with.

Available In:

Parameters

See playSilence for the parameter list.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.PlayAction object.

Examples

Play silence for 60 seconds, if 'Agent' is available, stop the play.
<?php

$call->playSilenceAsync(60)->done(function($playAction) use ($globalAgent) {
// For demonstration purposes only ..
if ($globalAgent->isAvailable()) {
$playAction->stop();
}
});

playTTS

This is a helper function that refines the use of play. This simplifies playing TTS.

Available In:

Parameters

$paramsarrayrequiredArray with the following properties:
textstringrequiredTTS to play.
languagestringoptionalDefault to en-US.
genderstringoptionalmale or female. Default to female.
volumenumberoptional Volume value between -40dB and +40dB where 0 is unchanged.
Default is 0.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.PlayResult object.

Examples

Play TTS.
<?php

$params = [ 'text' => 'Welcome to SignalWire!' ];
$call->playTTS($params)->done(function($playResult) {
// interact with $playResult..
});

playTTSAsync

Asynchronous version of playTTS. It does not wait the playing to completes but returns a Relay.Calling.PlayAction you can interact with.

Available In:

Parameters

See playTTS for the parameter list.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.PlayAction object.

Examples

Play TTS and stop it after 5 seconds.
<?php

$params = [ 'text' => 'Welcome to SignalWire!' ];
$call->playTTSAsync($params)->done(function($playAction) {
// interact with $playAction..

$playAction->stop();
});

prompt

Play one or multiple media while collecting user's input from the call at the same time, such as digits and speech.

It waits until the collection succeed or timeout is reached.

The prompt method is a generic method, see promptAudio, promptTTS or promptRingtone for more specific usage.

Available In:

Parameters

$collectarrayrequiredArray with the following properties:
typestringrequireddigits, speech or both.
mediaarrayrequiredList of media elements to play. See play for the array structure.
initial_timeoutnumberoptionalInitial timeout in seconds.
Default to 4 seconds.
volumenumberoptional Volume value between -40dB and +40dB where 0 is unchanged.
Default is 0.
  • To collect digits:
digits_maxnumberrequiredMax digits to collect.
digits_terminatorsstringoptionalDTMF digits that will end the recording.
Default not set.
digits_timeoutnumberoptionalTimeout in seconds between each digit.
  • To collect speech:
end_silence_timeoutnumberoptionalHow much silence to wait for end of speech.
Default to 1 second.
speech_timeoutnumberoptionalMaximum time to collect speech.
Default to 60 seconds.
speech_languagestringoptionalLanguage to detect.
Default to en-US.
speech_hintsarrayoptionalArray of expected phrases to detect.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.PromptResult object.

Examples

Ask user to enter their PIN and collect the digits.
<?php

$mediaToPlay = [
['type' => 'tts', 'text' => 'Welcome at SignalWire. Please, enter your PIN and then # to proceed']
];
$collect = [
'type' => 'digits',
'digits_max' => 4,
'digits_terminators' => '#',
'media' => $mediaToPlay
];
$call->prompt($collect)->done(function($promptResult) {
if ($promptResult->isSuccessful()) {
$type = $promptResult->getType(); // => digit
$pin = $promptResult->getResult(); // => pin entered by the user
}
});

promptAsync

Asynchronous version of prompt. It does not wait the collection to completes but returns a Relay.Calling.PromptAction you can interact with.

Available In:

Parameters

See prompt for the parameter list.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.PromptAction object.

Examples

Ask user to enter their PIN and collect the digits.
<?php

$mediaToPlay = [
['type' => 'tts', 'text' => 'Welcome at SignalWire. Please, enter your PIN and then # to proceed']
];
$collect = [
'type' => 'digits',
'digits_max' => 4,
'digits_terminators' => '#',
'media' => $mediaToPlay
];
$call->promptAsync($collect, $tts)->done(function($promptAction) {
// .. do other important things while collecting user digits..
if ($promptAction->isCompleted()) {
$promptResult = $promptAction->getResult(); // => Relay.Calling.PromptResult Object
}
});

promptAudio

This is a helper function that refines the use of prompt.
This function simplifies playing an audio file while collecting user's input from the call, such as digits and speech.

Available In:

Parameters

You can set all the properties that prompt accepts replacing media with:

urlstringrequiredHttp(s) URL to audio resource to play.

The SDK will build the media for you.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.PromptResult object.

Examples

Collect user's digits while playing an Mp3 file.
<?php

$collect = [
'type' => 'digits',
'digits_max' => 4,
'url' => 'https://cdn.signalwire.com/default-music/welcome.mp3'
];
$call->promptAudio($collect)->done(function($promptResult) {
if ($promptResult->isSuccessful()) {
$type = $promptResult->getType(); // => digit
$pin = $promptResult->getResult(); // => pin entered by the user
}
});

promptAudioAsync

Asynchronous version of promptAudio. It does not wait the collection to completes but returns a Relay.Calling.PromptAction you can interact with.

Available In:

Parameters

See promptAudio for the parameter list.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.PromptAction object.

Examples

Ask user to enter their PIN and collect the digits.
<?php

$collect = [
'type' => 'digits',
'digits_max' => 4,
'url' => 'https://cdn.signalwire.com/default-music/welcome.mp3'
];
$call->promptAudioAsync($collect)->done(function($promptAction) {
// .. do other important things while collecting user digits..
if ($promptAction->isCompleted()) {
$promptResult = $promptAction->getResult(); // => Relay.Calling.PromptResult Object
}
});

promptRingtone

This is a helper function that refines the use of prompt.
This function simplifies playing ringtone while collecting user's input from the call, such as digits and speech.

Available In:

Parameters

You can set all the properties that prompt accepts replacing media with:

namestringrequiredThe name of the ringtone. See ringtones for the supported values.
durationnumberoptionalDuration of ringtone to play.
Default to 1 ringtone iteration.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.PromptResult object.

Examples

Play US ringtone for 30 seconds while collect digits.
<?php

$params = [
'type' => 'digits',
'digits_max' => 3,
'name' => 'us',
'duration' => '30'
];
$call->promptRingtone($params)->done(function($promptResult) {
if ($promptResult->isSuccessful()) {
$type = $promptResult->getType(); // => digit
$pin = $promptResult->getResult(); // => user's digits
}
});

promptRingtoneAsync

Asynchronous version of promptRingtone. It does not wait the collection to completes but returns a Relay.Calling.PromptAction you can interact with.

Available In:

Parameters

See promptRingtone for the parameter list.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.PromptAction object.

Examples

Play US ringtone for 30 seconds while collect digits in asynchronous.
<?php

$collect = [
'type' => 'digits',
'digits_max' => 3,
'name' => 'us',
'duration' => '30'
];
$call->promptRingtoneAsync($collect)->done(function($promptAction) {
// .. do other important things while collecting user digits..

if ($promptAction->isCompleted()) {
$promptResult = $promptAction->getResult(); // => Relay.Calling.PromptResult Object
}
});

promptTTS

This is a helper function that refines the use of prompt.
This function simplifies playing TTS while collecting user's input from the call, such as digits and speech.

Available In:

Parameters

You can set all the properties that prompt accepts replacing media with:

textstringrequiredText-to-speech string to play.
languagestringoptionalDefault to en-US.
genderstringoptionalmale or female. Default to female.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.PromptResult object.

Examples

Ask user to enter their PIN and collect the digits.
<?php

$collect = [
'type' => 'digits',
'digits_max' => 3,
'text' => 'Please, enter your 3 digit PIN.'
];
$call->promptTTS($collect)->done(function($promptResult) {
if ($promptResult->isSuccessful()) {
$type = $promptResult->getType(); // => digit
$pin = $promptResult->getResult(); // => pin entered by the user
}
});

promptTTSAsync

Asynchronous version of promptTTS. It does not wait the collection to completes but returns a Relay.Calling.PromptAction you can interact with.

Available In:

Parameters

See promptTTS for the parameter list.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.PromptAction object.

Examples

Ask user to enter their PIN and collect the digits.
<?php

$collect = [
'type' => 'digits',
'digits_max' => 3,
'text' => 'Please, enter your 3 digit PIN.'
];
$call->promptTTSAsync($collect)->done(function($promptAction) {
// .. do other important things while collecting user digits..
if ($promptAction->isCompleted()) {
$promptResult = $promptAction->getResult(); // => Relay.Calling.PromptResult Object
}
});

record

Start recording the call and waits until the recording ends or fails.

Available In:

Parameters

$paramsarrayoptionalArray with the following properties:
beepbooleanoptionalDefault to false.
stereobooleanoptionalDefault to false.
formatstringoptionalmp3 or wav.
Default mp3.
directionstringoptionallisten, speak or both. Default to speak.
initial_timeoutnumberoptionalHow long to wait in seconds until something is heard in the recording. Disable with 0.
Default 5.0.
end_silence_timeoutnumberoptionalHow long to wait in seconds until caller has stopped speaking. Disable with 0.
Default 1.0.
terminatorsstringoptionalDTMF digits that will end the recording.
Default #*.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.RecordResult object.

Examples

Start recording audio in the call for both direction in stereo mode, if successful, grab 'url', 'duration' and 'size' from the RecordResult object.
<?php

$params = [
'stereo' => true,
'direction' => 'both'
];
$call->record($params)->done(function($recordResult) {
if ($recordResult->isSuccessful()) {
$url = $recordResult->getUrl();
$duration = $recordResult->getDuration();
$size = $recordResult->getSize();
}
});

recordAsync

Asynchronous version of record. It does not wait the end of recording but returns a Relay.Calling.RecordAction you can interact with.

Available In:

Parameters

See record for the parameter list.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.RecordAction object.

Examples

Start recording audio in the call for both direction in stereo mode and then stop it using the RecordAction object.
<?php

$params = [
'stereo' => true,
'direction' => 'both'
];
$call->record($params)->done(function($recordAction) {
// For demonstration purposes only ..
$recordAction->stop();
});

sendDigits

This method sends DTMF digits to the other party on the call. Allowed digits are 1234567890*#ABCD and wW for short and long waits. If any invalid characters are present, the entire operation is rejected.

Available In:

Parameters

$digitsstringrequiredString of DTMF digits to send.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.SendDigitsResult object.

Examples

Send some digits.
<?php

$call->sendDigits('123')->done(function($result) {
if ($result->isSuccessful()) {
// ...
}
});

sendDigitsAsync

Asynchronous version of sendDigits. It does not wait for the sending event to complete, and immediately returns a Relay.Calling.SendDigitsAction object you can interact with.

Available In:

Parameters

See sendDigits for the parameter list.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.SendDigitsAction.

Examples

Send some digits and then check if the operation is completed using the SendDigitsAction object.
<?php

$call->sendDigitsAsync('123')->done(function($action) {
// ...
// Later in the code for demonstration purposes only ..
$completed = $action->isCompleted();
});

tap

Intercept call media and stream it to the specify endpoint. It waits until the end of the call.

Available In:

Parameters

$taparrayrequiredArray with the following properties:
audio_directionstringrequiredlisten what the caller hears, speak what the caller says or both.
target_typestringrequiredProtocol to use: rtp or ws, defaults to rtp.
target_ptimenumberoptionalPacketization time in ms. It will be the same as the tapped media if not set.
codecstringoptionalCodec to use. It will be the same as the tapped media if not set.
  • To tap through RTP:
target_addrstringrequiredRTP IP v4 address.
target_portnumberrequiredRTP port.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.TapResult object.

Examples

Tapping audio from the call, if successful, print both source and destination devices from the TapResult object.
<?php

$tap = [
'audio_direction' => 'both',
'target_type' => 'rtp',
'target_addr' => '192.168.1.1',
'target_port' => 1234
];
$call->tap($tap)->done(function($tapResult) {
if ($tapResult->isSuccessful()) {
print_r($tapResult->getSourceDevice());
print_r($tapResult->getDestinationDevice());
}
});

tapAsync

Asynchronous version of tap. It does not wait the end of tapping but returns a Relay.Calling.TapAction you can interact with.

Available In:

Parameters

See tap for the parameter list.

Returns

React\Promise\Promise - Promise object that will be fulfilled with a Relay.Calling.TapAction object.

Examples

Tapping audio from the call and then stop it using the TapAction object.
<?php

$tap = [
'audio_direction' => 'both',
'target_type' => 'rtp',
'target_addr' => '192.168.1.1',
'target_port' => 1234
];
$call->tapAsync($tap, $device)->done(function($tapAction) {
// ... later in the code to stop tapping..
$tapAction->stop();
});

waitFor

Wait for specific events on the Call or returns false if the Call ends without getting them.

Available In:

Parameters

event1, event2, ..eventNstring or string[]requiredOne or more Relay.Calling.Call State Events

Returns

React\Promise\Promise - Promise object that will be fulfilled with true or false.

Examples

Wait for 'ending' or 'ended' events.
<?php

$call->waitFor('ending', 'ended')->done(function($success) {
if ($success) {
// ...
}
});

waitForAnswered

This is a helper function that refines the use of waitFor. This simplifies waiting for the answered state.

Available In:

Parameters

None

Returns

React\Promise\Promise - Promise object that will be fulfilled with true or false.

Examples

Wait for the 'answered' event.
<?php

$call->waitForAnswered()->done(function($success) {
if ($success) {
// ...
}
});

waitForEnded

This is a helper function that refines the use of waitFor. This simplifies waiting for the ended state.

Available In:

Parameters

None

Returns

React\Promise\Promise - Promise object that will be fulfilled with true or false.

Examples

Wait for the 'ended' event.
<?php

$call->waitForEnded()->done(function($success) {
if ($success) {
// ...
}
});

waitForEnding

This is a helper function that refines the use of waitFor. This simplifies waiting for the ending state.

Available In:

Parameters

None

Returns

React\Promise\Promise - Promise object that will be fulfilled with true or false.

Examples

Wait for the 'ending' event.
<?php

$call->waitForEnding()->done(function($success) {
if ($success) {
// ...
}
});

waitForRinging

This is a helper function that refines the use of waitFor. This simplifies waiting for the ringing state.

Available In:

Parameters

None

Returns

React\Promise\Promise - Promise object that will be fulfilled with true or false.

Examples

Wait for 'ending' or 'ended' events.
<?php

$call->waitForRinging()->done(function($success) {
if ($success) {
// ...
}
});

Events

All these events can be used to track the calls lifecycle and instruct SignalWire on what to do for each different state.

State Events

To track the state of a call.

stateChangeEvent dispatched when Call state changes.
createdThe call has been created in Relay.
ringingThe call is ringing and has not yet been answered.
answeredThe call has been picked up.
endingThe call is hanging up.
endedThe call has ended.

Connect Events

To track the connect state of a call.

connect.stateChangeEvent dispatched when the Call connect state changes.
connect.connectingCurrently calling the phone number(s) to connect.
connect.connectedThe calls are being connected together.
connect.failedThe last call connection attempt failed.
connect.disconnectedThe call was either never connected or the last call connection completed.

Play Events

To track a playback state.

play.stateChangeEvent dispatched when the state of a playing changes.
play.playingA playback is playing on the call.
play.errorA playback failed to start.
play.finishedThe playback has ended.

Record Events

To track a recording state.

record.stateChangeEvent dispatched when the state of a recording changes.
record.recordingThe call is being recorded.
record.no_inputThe recording failed due to no input.
record.finishedThe recording has finished.

Prompt Events

To track a prompt state.

promptThe prompt action on the call has finished.

Fax Events

To track a fax state.

fax.errorFaxing failed.
fax.finishedFaxing has finished.
fax.pageA fax page has been sent or received.

Detect Events

To track a detector state.

detect.errorThe detector has failed.
detect.finishedThe detector has finished.
detect.updateThere is a notification from the detector (eg: a new DTMF).

Tap Events

To track a tapping state.

tap.tappingThe tap action has started on the call.
tap.finishedTap has finished.

Digits Events

To track a send digits action state.

sendDigits.finishedDigits have been sent.

Ringtones

Here you can find all the accepted values for the ringtone to play, based on short country codes:

nameat, au, bg, br, be, ch, cl, cn, cz, de, dk, ee, es, fi, fr, gr, hu, il, in, it, lt, jp, mx, my, nl, no, nz, ph, pl, pt, ru, se, sg, th, uk, us, tw, ve, za