Call Screening

About

Call screening allows the original caller to record their name before forwarding the call to the final destination. When the forwarded call is answered, the recorded name is played back to the recipeint.

Assumptions

Steps

  1. Recieve Incoming Call and Answer event
  2. Use the Speak Sentence method to prompt user to record their name
  3. Receive the Speak Sentence Events
  4. Turn on Audio Recording
  5. Create Gather
  6. Recieve either gather event or timeout
  7. Turn off audio recording
  8. Get audio recording location
  9. Get the media location from the recordingId
  10. Transfer the call with whisperAudio

Recieve Incoming Call and Answer event

After setting up your application to recieve incoming calls with autoAnswer enabled. You will recieve two events back to back:

  1. incomingCall
  2. answer

Your server should reply with any HTTP 2xx code to acknowledge that the callback event was delivered. Any thing returned in the response besides the status code is ignored by Bandwidth.

Incoming Call Event Properties

Property Description
eventType The event type, value is incomingcall.
callId The call id associated with the event.
callUri The complete URL of the call resource for this event.
from The phone number or SIP address that made the call. Phone numbers are in E.164 format (e.g. +15555555555) -or- SIP addresses (e.g. identify@domain.com).
to The phone number or SIP address that received the call. Phone numbers are in E.164 format (e.g. +15555555555) -or- SIP addresses (e.g. identify@domain.com).
callState The state of the call, value is active.
applicationId The id of the application associated with phone number for this this incoming call.
time Date/time of event. Timestamp follows the ISO8601 format (UTC).

Example Incoming Call Event

POST /your_url HTTP/1.1
Content-Type: application/json; charset=utf-8
User-Agent: BandwidthAPI/v1

{
   "eventType"     : "incomingcall",
   "from"          : "+13233326955",
   "to"            : "+13865245000",
   "callId"        : "{callId}",
   "callUri"       : "https://.../{userId}/calls/{callId}",
   "callState"     : "active",
   "applicationId" : "{appId}",
   "time"          : "2012-11-14T16:21:59.616Z"
}

Answer Event Properties

Property Description
eventType The event type, value is answer.
to The phone number or SIP address that received the call. Phone numbers are in E.164 format (e.g. +15555555555) -or- SIP addresses (e.g. identify@domain.com).
from The phone number or SIP address that made the call. Phone numbers are in E.164 format (e.g. +15555555555) -or- SIP addresses (e.g. identify@domain.com).
callState The call state. Value will be active.
callId The call id associated with the event.
callUri The full URL of the call resource for this event.
tag String provided when call created.
time Date when the event occurred. Timestamp follows the ISO8601 format (UTC).

Example Answer Event

POST /your_url HTTP/1.1
Content-Type: application/json; charset=utf-8
User-Agent: BandwidthAPI/v1

{
  "eventType" : "answer",
  "from"      : "+15753222083",
  "to"        : "+13865245000",
  "callId"    : "{call-id}",
  "callUri"   : "https://.../{user-id}/calls/{call-id}",
  "callState" : "active",
  "time"      : "2012-11-14T16:28:31.536Z"
}

Use the Speak Sentence method to prompt user to record their name

In order to prevent the prompt from being recorded, you need to use the playAudio to speak a sentence before turning on recording.

For the purposes of this tutorial, we're using the text-to-speech features of the API. The same flow holds true if you wanted to use a pre-recorded message as well.

Request URL

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

Basic Parameters

Parameter Description
sentence The sentence to speak. MAXIMUM LENGTH 1000 CHARACTERS
gender The gender of the voice used to synthesize the sentence.
locale The locale used to get the accent of the voice used to synthesize the sentence.
voice The voice to speak the sentence.
tag A string that will be included in the events delivered when the audio playback starts or finishes.

For more options and configuration view the full documentation

Example Speak Sentence Request

POST https://api.catapult.inetwork.com/v1/users/{userId}/calls/{callId}/audio HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: {apiToken:apiSecret}

{
  "sentence": "Please state your name then press any key when you're done"
}

Receive the Speak Sentence Events

During the speak sentence Bandwidth will send two callbacks with the status of the sentence:

  1. {"eventType": "speak", "status": "started"}
  2. {"eventType": "speak", "status": "done"}

Speak Sentence Event Properties

Property Description
eventType The event type, value is speak.
status Values are started or done.
state Values are PLAYBACK_START or PLAYBACK_STOP.
callId The call id associated with the event.
callUri The full URL of the call resource for this event.
tag String provided when text-to-speech started.
time Date when the event occurred. Timestamp follows the ISO8601 format (UTC).

For more details view the full documentation.

Example Start Event

POST /your_url HTTP/1.1
Content-Type: application/json; charset=utf-8
User-Agent: BandwidthAPI/v1

{
  "callId"    : "{callId}",
  "callUri"   : "https://.../{userId}/calls/{callId}",
  "eventType" : "speak",
  "status"    : "started",
  "time"      : "2013-06-26T17:55:45.748Z"
}

Example Done Event

POST /your_url HTTP/1.1
Content-Type: application/json; charset=utf-8
User-Agent: BandwidthAPI/v1

{
  "callId"    : "{callId}",
  "callUri"   : "https://.../{userId}/calls/{callId}",
  "eventType" : "speak",
  "status"    : "done",
  "time"      : "2013-06-26T17:55:46.768Z"
}

Turn on Audio Recording

Once you receive the { "status": "done" } event for the sentence, you'll want to immediately turn on recording and create a gather.

Request URL

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

Basic Parameters

Parameter Description
recordingEnabled Indicates if the call should be recorded. Values true or false.
recordingFileFormat The file format of the recorded call. Supported values are wav (default) and mp3.

For more details view the full documentation.

Example Recording Toggle On

POST https://api.catapult.inetwork.com/v1/users/{userId}/calls/{callId}/ HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: {apiToken:apiSecret}

{
  "recordingEnabled": true
}

Create Gather

This solution uses the gather method to allow us to specify a interDigitTimeout and maxDigits: 1 so that we can stop recording easily after a specified duration has passed, -OR- the caller presses any digit.

Request URL

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

Basic Parameters

Parameter Description
maxDigits The maximum number of digits to collect, not including terminating digits (maximum 30).
interDigitTimeout Stop gathering if a DTMF digit is not detected in this many seconds (default 5.0; maximum 30.0).
tag A string you choose that will be included with the response and events for this gather operation.

For more details view the full documentation.

Example Create Gather

POST https://api.catapult.inetwork.com/v1/users/{userId}/calls/{callId}/gather HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: {apiToken:apiSecret}

{
  "maxDigits"         : "1",
  "interDigitTimeout" : "6"
}

Recieve either gather event or timeout

When either the user has pressed a digit or the timeout has passed, you'll get a callback indicating as such. Once we recieve the gather event, so long as it's not a hung-up event we want to now turn off recording. If the caller hangsup during the gather, the flow should end.

Gather Event Properties

Property Description
eventType The event type, value is gather.
state The state of the gather. Value is completed.
digits The digits collected from user.
reason max-digits - The maximum number of digits specified for the gather com.
terminating-digit - The digit specified in the gather com was entered.
inter-digit-timeout - A timeout occurred indicating the maximum amount of time to wait between digits, or before the first digit was pressed.
hung-up - Call was hung up thus terminating the gather.
callId The call id associated with the event.
gatherId The gather event unique id.
time Date/time of event. Timestamp follows the ISO8601 format (UTC).
tag String used when creating the gather

For more details view the full documentation.

Example Gather Event

POST /your_url HTTP/1.1
Content-Type: application/json; charset=utf-8
User-Agent: BandwidthAPI/v1

{
  "eventType" : "gather",
  "reason"    : "max-digits",
  "state"     : "completed",
  "digits"    : "5",
  "time"      : "2014-07-31T01:01:27Z",
  "callId"    : "{callId}",
  "gatherId"  : "{gatherId}",
  "tag"       : "{tag}"
}

Turn off audio recording

Once you receive the { "eventType" : "gather", "state": "completed" } event for the gather, you'll want to immediately turn off recording.

Request URL

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

Basic Parameters

Parameter Description
recordingEnabled Indicates if the call should be recorded. Values true or false.

For more details view the full documentation.

Example Recording Toggle On

POST https://api.catapult.inetwork.com/v1/users/{userId}/calls/{callId}/ HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: {apiToken:apiSecret}

{
  "recordingEnabled": false
}

Get audio recording location

When the recording has been finished, Bandwidth will send a callback to your server with the location of the recording. You can use this URL to playback the recording on any call.

Recording Event Properties

Property Description
eventType The event type, value is recording.
state The state of the recording, callback event values are complete or error.
status The state of the recording, callback event values are complete or error.
callId The call id associated with the event.
recordingId The unique id of the recording resource.
recordingUri The full URL of the recording resource.
startTime Date/time the recording started. Timestamp follows the ISO8601 format (UTC).
endTime Date/time the recording completed. Timestamp follows the ISO8601 format (UTC).

For more details view the full documentation.

Example Record Complete Event

POST /your_url HTTP/1.1
Content-Type: application/json; charset=utf-8
User-Agent: BandwidthAPI/v1

{
  "callId"       : "{callId}",
  "eventType"    : "recording",
  "recordingId"  : "{recordingId}",
  "recordingUri" : "https://.../{userId}/recordings/{recordingId}",
  "status"       : "complete",
  "startTime"    : "2013-08-19T16:56:57.643Z",
  "endTime"      : "2013-08-19T16:57:08.712Z"
}

Get the media location from the Recording

Once the recording is complete, we'll need to fetch the real location of the media resource

Request URL

GEThttps://api.catapult.inetwork.com/v1/users/{userId}/recordings/{recordingId}

Returned Properties

Property Description
id The unique id of the recordings resource.
startTime Date/time when the recording started. Timestamp follows the ISO8601 format (UTC).
endTime Date/time when the recording ended. Timestamp follows the ISO8601 format (UTC).
call The complete URL to the call resource this recording is associated with.
media The complete URL to the media resource this recording is associated with.
state The state of the recording, values are
- recording
- complete
- saving
- error

For more details view the full documentation.

Example Recording Information

GET https://api.catapult.inetwork.com/v1/users/{userId}/recordings/{recordingId} HTTP/1.1
Authorization: {apiToken:apiSecret}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "endTime"   : "2013-02-08T13:17:12.181Z",
  "id"        : "{recordingId}",
  "media"     : "https://.../media/{callId}-1.wav",
  "call"      : "https://.../calls/{callId}",
  "startTime" : "2013-02-08T13:15:47.587Z",
  "state"     : "complete"
}

Transfer the call with whisperAudio

The final step is to transfer the original call to the desired forwarding destination. Using the { "state": "transferring" } update to the call will allow you to specify a whisper to be played to the recipient before the two calls are bridged.

In this case, you'll use the media-url from above as the fileUrl within the whisperAudio.

Request URL

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

Basic Parameters

Parameter Description
state transferring to transfer the incoming call to another line.
transferTo Phone number or SIP address that the call is going to be transferred to.
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.
callbackUrl The server URL where the call events for the new call will be sent upon transferring.
whisperAudio Audio to be played to the caller that the call will be transferred to.

For more details view the full documentation.

Example Transfer Call with Whisper

POST https://api.catapult.inetwork.com/v1/users/{userId}/calls/{callId}/ HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: {apiToken:apiSecret}

{
  "state"            : "transferring",
  "transferCallerId" : "private"
  "transferTo"       : "+18382947878",
  "callbackUrl"      : "{{your-url}}",
  "whisperAudio"     : {
    "fileUrl" : "{{mediaUrl-from-above}}"
  }
}

Wrapping it up

Once the original inbound call has been updated with the { "state": "transferring" } to transfer the call, Bandwidth will play a default ringing to the inbound call while the call is transferred. When the final destination answers the call and the whisper is finished, the two will be bridged together.

results matching ""

    No results matching ""