# 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"
```

<br>

### 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](https://docs.telcobridges.com/wiki/Customer_application_framework:play_audio_files#Play_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
```

<br>

### 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](https://docs.telcobridges.com/wiki/Toolpack:Configuring_Audio_Prompts_C)

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://prosbcdocs.telcobridges.com/configuration-details/configuration-by-web-portal-category/routing-scripts/development-guides-and-tutorials/playing-prompts-announcements-and-tones.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.