Contents
Customizing Music on Hold
Starting with version 8.1.102.31, SIP Server lets you customize music for music-on-hold treatments. When the music-on-hold feature is activated, it applies to scenarios when the hold action is performed by an agent within the duration of the call explicitly (by THoldCall), or implicitly (by TAlternateCall, TInitiateTransfer, or TInitiateConference).
New options are supported on the Switch object level:
- music-on-hold for Routing Point DNs
- default-music for Agent Logins
When custom music-on-hold is enabled on the Routing Point with the music-on-hold configuration option, or with the music-on-hold key in AttributeExtensions of TRouteCall, it remains attached (sticks) to the call until the call is released. If a TRouteCall request arrives with an empty value of the music-on-hold key in AttributeExtensions, the custom music-on-hold stickiness is removed from the call. If call routing fails, the custom music-on-hold setting is rolled back to the previous value.
The value of the music-on-hold option is attached to calls distributed via this Routing Point and used for playing the music-on-hold later.
When the default-music option is set for an Agent Login object, the setting applies only to a call established by the agent who activated the Hold operation.
Music File Priority
The following settings determine the order of priority—from highest to lowest—in which a music file is played for a call on hold:
- The music key of AttributeExtensions in THoldCall, TAlternateCall, TInitiateTransfer, TInitiateConference requests, which initiate the Hold operation for a call.
- The music-on-hold key of AttributeExtensions in TRouteCall (if there are several TRouteCall requests for this call containing this key, the value from the last one is applied).
- The music-on-hold option on a Routing Point DN (if a call is passed through several Routing Points containing this option, the value from the last one is applied).
- The default-music option on an Agent Login level.
- The default-music option on an agent's Extension DN level.
- The default-music option on a SIP Server Application level.
How it Works in Conferences
The custom music-on-hold setting is not applied to conferences and not shared when a consultation call is merged with the main call. However, the custom music-on-hold setting remains associated with the call, and if only two participants are left on the call, the custom music-on-hold setting will be applied if the caller is placed on hold. When a new party joins the conference, the custom music-on-hold setting is not applied.
For multi-site conferences support, SIP Servers must propagate full information about call parties. See "Providing Call Participant Info" in the SIP Server Deployment Guide for information on how to enable it.
How it Works in Transfers
The custom music-on-hold setting is transferred with the call, which includes call routing, single-step transfers, two-step transfers, and call forwarding. In multi-site transfers, the ISCC connection is used.
If a call is transferred through a Routing Point that has a custom music-on-hold setting, the new music-on-hold setting will be applied to the next Hold scenario.
Configuration Options
music-on-hold
Setting: [TServer] section, Routing Point DN
Default Value: An empty string
Valid Values: The subdirectory and name of the audio file in the MCP root directory, using the following format: <subdirectory>/<music file name>; for example: music/in_queue_welcome.wav
Changes Take Effect: For the next call
Specifies the name of the file that is played for the music-on-hold treatment when one of the parties in the call is put on hold. The option applies to calls that are passed through this Routing Point, unless a call is distributed with the TRouteCall request that contains the music-on-hold key in AttributeExtensions.
default-music
Setting: [TServer] section, Agent Login
Default Value: An empty string
Valid Values: The subdirectory and name of the audio file in the MCP root directory, using the following format: <subdirectory>/<music file name>; for example: music/in_queue_welcome.wav
Changes Take Effect: For the next call
Specifies the name of the file that is played for the music-on-hold treatment to a caller when a respective agent places the call on hold. The option applies to calls distributed to this agent, unless a call is passed through a Routing Point with the music-on-hold option, or a call is distributed with the TRouteCall request that contains the music-on-hold key in AttributeExtensions.
AttributeExtensions
Key: music-on-hold
Type: String
Valid Values: The subdirectory and name of the audio file in the MCP root directory, using the following format: <subdirectory>/<music file name>; for example: music/in_queue_welcome.wav
Request: TRouteCall
Specifies the name of the file that is played for the music-on-hold treatment when one of the parties in the call is put on hold.
Feature Limitations
- In multi-site deployments with the music-on-hold setting enabled in AttributeExtensions, the iscc-pass-extensions key in AttributeExtensions must not be set to a value of local, because it prevents extensions being passed through ISCC to a remote site.
- In Business Continuity (BC) deployments, the custom music-on-hold setting is propagated with a call transfer in DR-forward scenarios only if the Call Overflow feature is enabled. That is, the following SIP Server Application options must be set in the [extrouter] section:
- cof-feature=true
- default-network-call-id-matching=sip