Skip to main content

Call Whisper

A call whisper allows the callee (receiver of the call) to receive an audio message before the call is connected and allows the callee to accept or reject the incoming call. The audio message can contain information such as the source or purpose of the call.

The <Dial> verb in SignalWire Compatibility XML makes it very easy to add a call whisper feature by providing a call screening URL that controls the call once the callee picks up, while the caller continues to hear ringing (assuming answerOnBridge is set to true). If the call is being answered by a client created using the SignalWire Client SDKs, the URL attribute on the <Client> noun can be used. If the call is being answered by a phone number, the same attribute is available using the Dial verb-noun <Number>.

The <Dial> attribute can point to a URL that returns XML with the <Play> or <Say> verbs to play a message to the callee before connecting the call. It can also use <Gather> and <Hangup> verbs, allowing the callee to accept or reject the call by pressing a key.

Example XML Bin to Redirect Call to Agent​

<?xml version="1.0" encoding="utf-8"?>
<Response>
  <Dial>
    <Number url="https://spacename.signalwire.com/laml-bins/5e902c09-a4d5-47b8-81b9-892943f2e5e7">123-456-7890</Number>;
  </Dial>
</Response>

The <Number> URL included in the above example can point to an XML Bin (or a URL with SignalWire Compatibility XML), which plays a message or uses <Gather> to capture the callee's actions. Here is more information around the Gather verb.

Below is the XML for the XML Bin for the <Number> URL <https://<spacename>.signalwire.com/laml-bins/5e902c09-a4d5-47b8-81b9-892943f2e5e7> that is listed above.

<?xml version="1.0" encoding="utf-8"?>
<Response>
<!--
 <Say voice="alice">You are getting a call on the support line, the next voice you will hear is the customer.</Say> 
-->
  <Gather action="https://spacename.signalwire.com/laml-bins/be5db310-27bc-44c7-ae19-272d1822fc77" numDigits="1" input="dtmf">
    <Say voice="alice">Press any key to accept call from 
    <say-as interpret-as="characters" />
    or hangup up now to disconnect</Say>
  </Gather>
  <Say>You did not enter anything</Say>
</Response>

The Gather action URL seen in the above XML Bin can have an empty response for testing purposes. If needed, add an audio message saying "connecting now to the caller" by adding the text between <Say></Say>. Create the XML Bin with one of the following XML examples and add the Bin's URL to the Gather action section as seen above with <https://<spacename>.signalwire.com/laml-bins/be5db310-27bc-44c7-ae19-272d1822fc77>

Empty Response (Accepts call but no other action made):​

<?xml version="1.0" encoding="utf-8"?>
<Response>
</Response>

Say Verb Option (Audio statement plays, then the call is connected):​

<?xml version="1.0" encoding="utf-8"?>
<Response>
<Say>Connecting you to the caller now.</Say>
</Response>

Call is Rejected by Digits Pressed by Callee:​

<?xml version="1.0" encoding="utf-8"?>
<Response>
  <Hangup />
</Response>

Complete the Whisper call scenario by connecting the first XML Bin URL for redirecting the call to an agent, to a phone number on your SignalWire account.

Please note: Replace all XML Bin URLs in the examples above with your SignalWire XML Bin URLs.