PlayPrompt

Purpose

Use PlayPrompt to play a prompt.

A screen capture of the Action PlayPrompt window

Description

Before you can use PlayPrompt, you must both construct the prompt and make sure it is stored in the prompt directory that the state table uses. You must also select the prompt directory in the State Table window.

For the PlayPrompt 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).

The prompt being played can be interrupted by DTMF detection. If voice detection is set to active, a caller can also interrupt the prompt just by speaking (to activate voice detection, set system variable SV217 to 1 ). For both DTMF and voice interrupts, by setting theForce Play option you can ensure that PlayPrompt always plays the complete prompt. With DTMF detection, there are additional options available that allow you to configure how the interrupt is handled:

PlayPrompt plays the prompt only until the caller interrupts it by pressing any DTMF key
PlayPrompt plays the prompt only until the caller interrupts it by pressing one of a set of DTMF keys you specify

If you use the PlayPrompt panel to specify a set of DTMF keys for interrupting the prompt, and the caller subsequently presses any other key, that key press is flushed and ignored. When the caller presses a valid stop key, you can determine which key they pressed by using the GetKey or GetData action. The system stop, pause, reverse, and fast forward keys (as specified by the corresponding system parameters) are ignored, as are any values in the system parameter System: Play/Record: Alternate stop keys (SV183).

If a fax tone is detected and Force Play was not selected, the action is terminated. Check the value set in the System:Action additional information system variable SV180.

If a network delay causes the first prompt in your application to start late, missing the first few milliseconds of voice, you can force play a silent prompt before the first prompt. This gives the network time (the duration of the silent prompt) to complete the connection to Blueworx Voice Response before the first audible prompt is played.

If a voice segment is not found, the System: PlayPrompt status variable (SV 130) is set to -1. The action continues regardless of the success or failure to play the voice segment. You can test the value of the System: PlayPrompt status variable to determine if a voice segment was missing, and take appropriate action in the state table. Subsequent attempts to play voice segments set the System: PlayPrompt status variable to 0 if successful or -1 if not.

If a PlayPrompt action plays, or starts to play, at least one voice segment, the PlayPrompt action returns the Succeeded result. If a PlayPrompt action is unable to play any voice segments, for example, they do not exist, the PlayPrompt action returns the Nothing Played result (if it would otherwise have succeeded).

Any attempt to play a missing voice segment generates error 300 (Voice segment not found) in the error log.

PlayPrompt 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 prompt, precede this action with a ControlMusic action and set the fade time to 100.

If the first 0.8 seconds a prompt is unexpectedly force-played, this can be as a result of a preceding GetData, GetFindData, or GetFindName. For more information see GetData, GetFindData, and GetFindName.

Parameters

The parameters for PlayPrompt identify the prompt, define the values for any prompt parameters, and control whether the caller can interrupt the prompt with input.

Prompt. Identifies the prompt you want the action to play.
Parameters. This parameter is activated only when the prompt expects parameter values. It contains the value for each parameter expected by the prompt.

In addition, you must specify one of the following:

Force Play. The prompt is force played; that is, the application plays the prompt in its entirety to the caller. The prompt cannot be interrupted by a DTMF key, voice, or fax tone. When Force Play is selected, all input and other events are flushed when the action completes. As a result, any queued DTMF, voice interrupt detection or fax tones are lost.
All DTMF Keys. The prompt is interrupted when the caller presses any DTMF key.
Select DTMF Keys. The prompt is interrupted when the caller presses one of a set of DTMF keys that you define. You can define the set of DTMF keys in one of two ways:
- Specify the DTMF keys as constants: select Const, then type (in the empty field) the names of the keys you want to use (for example, 12AB#).
- Specify the DTMF keys as a variable. First define a variable that contains the names of the DTMF keys you want to use, then select Var, press DTMF Keys, and select the name of the variable you defined.

Possible results

PlayPrompt can have one of the following results:

Succeeded

The prompt was found and successfully played to the caller, either partly or in full (a prompt that references a truncated voice file containing at least 128 bytes of the original data is still playedif more than 200 milliseconds of voice is lost a warning message is raised). If the prompt is force played, it is played to the end without interruption.

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. To retrieve (and flush) the key, use the GetKey (seeGetKey) or GetData (see GetData) state table actions.
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) ).
5: A bad operation code from a compare, an assign, or a logical error was detected; play was stopped.

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.

Line Problem: The prompt was not played, because there was a problem with the voice channel on which it was supposed to be played.
Nothing Played: The prompt 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:

Force Play "TRUE", "FALSE", or "FALSE_WITH_SELECT_KEYS".
If you specify "FALSE_WITH_SELECT_KEYS", you must also specify either the name of a variable that defines the names of the keys, or specify the names as constants.
Name of prompt.
Variable or constant passed to prompt.

For example:

label: "Check Edges"
        PlayPrompt("TRUE", Date, "19931225")
          edge EDGE_PP_COMPLETED:                 completed
          edge EDGE_PP_LINE_PROBLEM:             line_problem
          edge EDGE_PP_NOTHING_PLAYED:   nothing_played
          edge EDGE_HUP:                                   hup
        ;
        PlayPrompt("FALSE", Phone, "0962844433");
PlayPrompt("FALSE_WITH_SELECT_KEYS", "12AB#", Ordinal, 122344);

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