Objective

Call Whisper, also commonly referred to as Call Screening, involves playing a message to the callee while the caller continues to hear ringing. It can provide additional information such as the source or purpose of the call to the callee before the call begins and even allow the callee to accept or reject the call based on that information.

A common question after implementing a call whisper use case is why the call whisper message is not heard in the call recording and if / how it can be. 

This article explains how to capture a call whisper in your call recording. 

Product

Programmable Voice

Procedure

Below are the procedures for recording a call whisper.

Outbound Call with a Call Whisper

The most common recording method customers will use to try and capture a call whisper is using the <Dial> record attribute. However, this will not capture the call whisper, even with dual channel record from ringing enabled, as the media stream is not yet established when the call whisper is played.

The only way to capture a call whisper in a recording is with the call Recording resource of the API, which is typically triggered by the "in-progress" status callback event.

Here is how this is implemented:

1. Configure a statusCallback URL for the child call leg which will hear the call whisper. This is done within either the <Client> or <Number> TwiML noun. 

2. Configure the statusCallbackEvent attribute within <Client> or <Number>. At a minimum, this must include the 'in-progress' event. This must be configured as only 'completed' event will be configured by default.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
     <Dial answerOnBridge="true">
          <Client statusCallbackEvent="initiated ringing answered completed" statusCallback="your_server_url/statusCallback" url="your_server_url/whisper">
               <Identity>Twilio Agent</Identity>
          </Client>
     </Dial>
</Response>

 

3. Add some logic at the status callback URL to check if the call status is 'in-progress', and if so, start a recording with the callSid in the request. Here is some sample code implementing this solution with the NodeJS helper library:

exports.status = function status(requestBody) {
     if (requestBody.CallStatus == "in-progress") {
          client.calls(requestBody.CallSid)
          .recordings
          .create({
               recordingChannels: 'dual'
          })
     .then(recording => {
          console.log("Recording enabled: " + recording.sid);
     })
     .catch(e => {console.log('Got an error:', e.code, e.message)});
     }
     return
};

*NOTE: this recording will not contain any audio from the parent call leg prior to the call whisper. If a dual channel recording is enabled, audio from both call legs will be recorded after the call whisper.

Inbound Calls with a Call Whisper

While an inbound call may not technically contain a "call whisper", we have customers who will call it that; hence we have some guidance on this below. For example, we had a customer receiving calls to their Twilio number, and as soon as the call is answered, a message saying "this call will be recorded for training and audit purposes..." After this message is played, the call is then transferred to an agent.

This is a common use case, and it's also common that customers would want to ensure this message is recorded (e.g. if they are audited, they want to have proof that they informed all callers that their calls were recorded). 

Recording Inbound Calls

As shown in Recording Incoming Twilio Voice Calls, recording inbound calls must be done with the API. This is basically the same method as for outbound calls shown above. But you would need to set the status callback on the Twilio number ("Call status changes") instead of using TwiML. Just like for outbound calls, this webhook will begin a recording with the Recording resource of the API upon the "in-progress" callback and you could even use the exact same url and code.

The only time this method cannot be done is if a customer is using Studio.

Recording Inbound Calls in Studio

If a customer is receiving calls to a Studio Flow, then the Call status changes webhook cannot be used since Studio requires that field to update the Flow. In addition, Studio does have a Call Recording widget which enables a recording on an active call via API, but this cannot be the first widget in your Flow or the call will result in a "busy" status. 

This is the predicament with recording a call whisper message for an inbound call using Studio.

There is however a way to get around it.

Solution: Recording the Call Whisper for Inbound Studio Calls

Let's say your Flow looks like below where the Recording widget (call_recording_1) is executing after the Whisper message played by say_play_1 widget. Hence, the whisper message is not being recorded.

If we move the Call Recording widget before the Say/Play, we will get a busy signal (it cannot be the first widget in the call). To get around this, you can first play a silent audio file for less than 1 second, then enable the recording, then play the whisper message.

Here's the step by step.

1. Create or download a silent audio file. Here's one on Github which is 500ms.

2. After downloading it, upload it as a Twilio Asset and copy the 'PATH'.
**it's recommended to upload your file as a Twilio Asset to ensure it remains active. Relying on an external audio file could result in a failure if the file ever becomes unreachable. 

3.  Add a new Say/Play widget to the beginning of the Flow and update it's configuration to play the audio file from the Twilio asset PATH, as shown in the below screenshot.
**The red Trigger widget should be connected to the newer Say/Play widget on 'Incoming Call'.

 

 


4. Then connect this new Say Play widget to the Call Recording widget. 

5. Then connect the Call Recording widget to the call whisper message.

6. Finally Click Publish
 

Your Flow should now look something like this: