PlayVoiceMessage

Purpose

Use PlayVoiceMessage to play a message that has been retrieved either from a mailbox (using CheckVoiceMessages) or from workspace.

Description

When a message that has been retrieved from a mailbox (using CheckVoiceMessages) is played successfully all the way through to the end, the status changes from Checked to Listened. If the message has just been recorded in workspace, you can use PlayVoiceMessage to play it back to a caller before sending it to the intended recipient.

For the PlayVoiceMessage action to succeed, the voice channel must already be connectedthis is achieved through the successful completion of either an AnswerCall or a Makecall action. For an incoming call, the voice channel can also be connected prior to an AnswerCall action, if the system parameter Connect Voice Channel Before Answer is enabled (this parameter is only available if you are logged on as field).

While a voice message is playing, the caller can press keys to fast-forward, pause, reverse, or stop. System parameters in the Application Server Interface parameter group set these keys as follows:

In addition, system parameter SV183 can be used to specify other DTMF keys that can stop the action. See System: Play/Record: Alternate stop keys (RW) (SV183) for more information.

To resume after a pause, the caller must press the pause key again. If the caller does not resume after pressing the pause key (by pressing the pause key again), playing continues when the pause times out. The pause time out is configurable using the Play/Record Voice Maximum Pause (seconds) system parameter in the Blueworx Voice Response parameter group. The default value is 10 seconds.

When interrupt by voice detection is active, the caller can interrupt PlayVoiceMessage by speaking.

If a fax tone is detected, the action is terminated.

If the sender requested acknowledgment of the message (using the Receipt Acknowledgment parameter of ChangeMessageAttributes), the message is sent to the sender's mailbox as a New message when the recipient plays the message and the Message: Receipt acknowledgment status system variable (SV161) has a value of 2, which indicates that the message was listened to.

PlayVoiceMessage can be used with background music to produce a voice-over effect. If you don't want background music playing at the same time as the message, precede this action with a ControlMusic action and set the fade time to 100.

All user input and other events are flushed both before this action starts, and when it completes. As a result, any queued DTMF, voice interrupt detection, or fax tones are lost.

Parameters

When a message is initially recorded, it is held in workspace until the caller confirms it is to be sent, when it is put into a mailbox. You can choose to play a message from either workspace or a mailbox by selecting one of the buttons next to Message in Mailbox or Message in Workspace.

Possible results

PlayVoiceMessage can have one of the following results:

Succeeded

The message was found and successfully played to the caller, either partly or in full (a truncated message that contains at least 128 bytes of the original data is still playedif more than 200 milliseconds of voice is lost a warning message is raised).

The system variable System: Action additional information (SV180) is set to one of the following values:

0

The action completed without interruption.

1

The caller pressed a DTMF key; play was interrupted.

2

Voice was detected; play was interrupted. Use WaitEvent to flush the voice event from the queue (see WaitEvent). Detection of voice interrupt is enabled by setting SV217 to 1 (see System: Voice interrupt detection: On/Off (RW) (SV217) ).

3

Fax tone was detected; play was interrupted. Detection of fax tone is enabled by setting SV227for possible values see System: Fax detection (SV227).

4

A custom server event occurred; play was interrupted. To retrieve the event, use the WaitEvent state table action (see WaitEvent). Detection of a custom server event is enabled by setting SV546 to 1 (see System: Host Interrupt Detection: On/Off (RW) (SV546) ).

Note: If you want to use the information in SV180, you must check it immediately after a state table action because it is reset by other actions.

Voice Channel Problem

The message was not played, because there was a problem with the voice channel on which it was supposed to be played.

Voice Record Not Found

The message does not exist, or has been truncated to less than 128 bytes of data.

Caller Hung Up

The caller has hung up.

ASCII syntax

When using an ASCII editor, code this action with these parameters in the following order:

• "MSG_IN_MAILBOX" or
• "MSG_IN_WORKSPACE"

For example:

label: "Check Edges"
        PlayVoiceMessage("MSG_IN_MAILBOX")
          edge EDGE_PLAYVCE_COMPLETED:   completed
          edge EDGE_PLAYVCE_LINE_PROBLEM:       line_problem
          edge EDGE_PLAYVCE_NOT_FOUND:  not_found
          edge EDGE_HUP:                                  hup
        ;
        PlayVoiceMessage("MSG_IN_WORKSPACE");

The parameters and edges are described above under "Parameters" and "Possible results". For more information, see Testing a state table using the debugger.