Playing prompts, announcements, and tones

Introduction

New feature in release 2.6, all bridges may have these parameters. These can be used to play IVR prompts (audio files) in different states of the call flow.

• announcement_tone (played before outgoing call is routed)

• ring_tone (played after when waiting for outgoing call to answer)

• busy_tone (played if outgoing call failed)

• disconnect_tone (played after the call has reached it's maximum duration)

Example to play an announcement to incoming call (before routing outgoing call, regardless if a matching route is found or not):

 bridge[:announcement_tone ] = "my_announcement.wav"

Example to play a ring-tone while the outgoing call is ringing:

 bridge[:ring_tone] = "my_ring_tone.wav"

Example to play an audio file when outgoing call fails (no route, or outgoing call is refused):

 bridge[:busy_tone] = "my_busy_tone.wav"

Example to play an audio file when call has reached the maximum allowed duration:

 bridge[:disconnect_tone] = "your_account_balance_is_empty.wav"

Announcement file path format and options

All file plabyacks (:announcement_tone, :busy_tone, :ring_tone, :disconnect_tone) inside bridge parameters use this format.

"file1.wav:repeat:start_off:end_off,file2.wav:repeat:start_off:end_off,file3.wav:repeat:start_off:end_off"

Optional parameters:

• repeat: number of times to play the file (0 and 1 have the same result)

• start_off: Start offset in milliseconds

• end_off: End offset in milliseconds

Http and other path formats are described here: Path format

Example 1

The following example will play file1.wav once, and then play file2.wav in a loop:

 "file1.wav,file2.wav:-1"

Example 2

The following example will play file1.wav from a start offset of 1 second to an end offset of 3 seconds, followed by file2.wav being played two times from second 5 to second 10.

 "file1.wav:0:1000:3000,file2.wav:2:5000:10000"

Example 3

The following example will play file1.wav once, ending at an offset of 30 seconds.

 "file1.wav:0:0:30000"

announcement_tone

 params[:bridge][:announcement_tone] = "announcement.wav" 

Audio file played on the incoming call before any outgoing call is placed. The outgoing call occurs when the file finished playing.

announcement_tone options

announcement_tone_answer

 params[:bridge][:announcement_tone_answer] = "yes"

Forces an answer of the call before playing the announcement. Default if argument not provided is "no", in which case call is only alerted with in-band media.

announcement_code_detect

This option allows that the tone detection is enabled during the announcement play.

Collected digits can be inserted into the CDR logs (radius attribute "Telcob-CollectedDigits", or text CDR variable @{CollectedDigits}).

Collected digits can also be sent back to routing script, which is called again with the same call attributes, except that the called number is replaced by the collected digits.

Code detect has multiple options, as shown in the following code:

 code_detect = {
   :type                   => :DTMF,   # :DTMF or :MFR1 tone detection.
                                       # Default is MFR1.
   :prefix                 => "",      # Prefix (digits) that is removed from collected digits.
                                       # Default is empty.
   :suffix                 => "",      # Suffix (digits) that is removed from collected digits
                                       # and causes routing script to be immediately called.
                                       # Default is empty.
   :suffix_removal         => false,   # Controls the removal of the suffix from the collected digit string that's reported to routing script.
                                       # Default is false
   :timeout                => 0,       # Inter-digit timeout (ms) after which collected digits are passed to the routing script.
                                       # Use 0 for "no timeout".
                                       # Default is 1000ms
   :barge_in_interruption  => true,    # When enabled, playing announcement is stopped as soon as first digit is collected.
                                       # Default is true.
   :proceed_on_play_done   => false,   # When true:  Outgoing call is made after announcement finishes playing.
                                       #             Routing script is not called again.
                                       # When false: Outgoing call is never made.
                                       #             Digits are collected until timeout or suffix match,
                                       #             then routing script is called again.
                                       # Default is false.
   :cas_on_hook            => false,   # Specific for CAS-R1 calls. Makes CAS bits switch to "on-hook" when announcement finished playing
                                       # (but the call is not "terminated" from Toolpack point of view)
                                       # Default is false.
   :cas_on_hook_delay      => 0,       # Duration of cas bits "on-hook" state.
                                       # Only effective if cas_on_hook is set to true.
                                       # Value of 0 stands for "infinite delay".
                                       # Default is 0.
   :repeat_delay           => 0,       # Delay between repetition of the announcement. The announcement will repeat
                                       # itself every "repeat_delay" until a code is detected (suffix match or timetout).
                                       # Value of 0 stands for "infinite delay" (no repeating).
                                       # Default is 0.
 }

Example 1: Collect DTMF digits, and call routing script again with collected digits upon timeout or suffix match.

 code_detect = { :type => :DTMF, :suffix => "#", :timeout => 5000 }
 params[:bridge][:announcement_code_detect] = code_detect

Example 2: Collect digits during the announcement (for CDR logs), then proceed (make outgoing call) after announcement finishes playing

 code_detect = { :type => :DTMF, :timeout => 0, :barge_in_interruption => false, :proceed_on_play_done => true }
 params[:bridge][:announcement_code_detect] = code_detect

Controlling what happens after announcement

The routing script can control what happens with the call after the announcement finishes playing:

• An outgoing call is made

• Incoming call is hung-up

• Do nothing (wait for the incoming call to hang-up)

An outgoing call is made

This happens when the script has returned matching routes (and did not raise RoutingException)

Incoming call is hung-up

This happens when the script returns no routes (in which case base_routing will raise RoutingException with cause :no_route).

It also happens when the script explicitly raises RoutingException.

The incoming call will be terminated with the specified cause. For example

   raise RoutingException, :temporary_failure

(See "Reason values" section in this page for list of available causes)

Do nothing (wait for the incoming call to hang-up)

If a filter raises RoutingException with code :ok, then the incoming call will not be terminated at the end of the announcement play. Announcement digit collection will remain active if appropriate. For example:

   raise RoutingException, :ok

ring_tone

 params[:bridge][:ring_tone] = "ringing.wav" 

Audio file played on the incoming call while waiting for the outgoing call to be answered.

Ring tone playback can also be configured in the Web Portal, from the incoming call's profile (under "Tones and Call Progress Options").

Routing script has precedence over profile (a routing script that fills params[:bridge][:ring_tone] will override the profile's ring tone behavior).

ring_tone options

ring_tone_state

 params[:bridge][:ring_tone_state] = :alerted

Call state from which ring tone is being played. Available values are:

• immediately: Ring tone starts playing immediately on the incoming leg

• accepted: Ring tone starts playing as soon as outgoing call is accepted

• callprogress: Ring tone starts playing as soon as "call progress" is received on the outgoing call

• alerted (default): Ring tone starts playing only once outgoing call is alerted (but won't play if alert indicates early media from outgoing call)

This option also applies when params[:bridge][:ring_tone] are not used, because it also applies to ring tone playback configured in the Web Portal, from the incoming call's profile.

busy_tone

 Toolpack 2.8 and above:
   params[:bridge][:busy_tone] = "no_route.wav"

 Note: Obsolete name (toolpack 2.7.153 and earlier, but still supported in recent releases):
   params[:bridge][:call_progress_tone] = "no_route.wav" 

Audio file played on the incoming call when outgoing call fails (never answered).

Note that announcement_tone, if used, is played before the outgoing call attempt is made, and thus before the busy_tone.

Busy tone playback can also be configured in the Web Portal, from the incoming call's profile (under "Tones and Call Progress Options").

Routing script has precedence over profile (a routing script that fills params[:bridge][:busy_tone] will override the profile's busy tone behavior).

Special value "none" can be used by routing script to force playing nothing (as empty string would default to profile's behavior)

busy_tone options

busy_tone_answer

 params[:bridge][:busy_tone_answer] = "yes"

Forces an answer of the call before playing the busy tone. Default if argument not provided is "no", in which case call is only alerted with in-band media.

disconnect_tone

 params[:bridge][:disconnect_tone] = "max_duration.wav" 

Audio file played on the incoming call when call duration (:max_call_duration) is reached. Then the leg will be terminated with specified reason (:call_duration_reason).

disconnect_tone options

max_call_duration

 params[:bridge][:max_call_duration] = "60000" 

Maximum call duration in millisecond. This timer is started when entering answer state.

call_duration_reason

 params[:bridge][:call_duration_reason] = :resource_unavailable 

Drop both legs with this reason when call duration (:max_call_duration) is reached.

Managing audio prompts through Web Portal

Audio prompts can be uploaded or deleted from the TMedia unit through the Web Portal: Managing audio prompts

Prompts management must be done using the Web Portal of the primary server (in systems with redundant TMedia units or redundant host servers). The file will automatically get replicated to the secondary server.

Managing audio prompts manually

Any file on the TMedia host file system can be played. This means it's possible to manage prompts through ssh/scp.

The default (replicated) prompts folder

By default, when playing a prompt, Toolpack will look in the default prompts folder:

/lib/tb/toolpack/pkg/prompts

The root of this "prompts" directory is automatically replicated to secondary unit of redundant setups (1+1, N+1, redundant hosts). Sub-folders won't be replicated.

Any prompt play request without explicit file path will map to this folder. For example:

 params[:bridge][:busy_tone] = "no_route.wav" 

This will correspond to file /lib/tb/toolpack/pkg/prompts/no_route.wav

Relative file paths

Any file path that begins with "file://" is considered relative to the tbstreamserver application's working directory:

/lib/tb/toolpack/setup/12358/2.8/apps/tbstreamserver/

(Where "2.8" may be replaced by the current major version of your system)

For example:

 params[:bridge][:busy_tone] = "file://my_folder/no_route.wav" 

This will correspond to file /lib/tb/toolpack/setup/12358/2.8/apps/tbstreamserver/my_folder/no_route.wav

Absolute file paths

Absolute paths can also be provided. For example:

 params[:bridge][:busy_tone] = "file:///root/my_folder/no_route.wav" 

This will correspond to file /root/my_folder/no_route.wav