ADDRESS VOX Commands › Voice Commands › CALLPLAY Command

CALLPLAY Command

The CALLPLAY command initiates a telephone call and plays one or more prerecorded voice messages. It sets the hook state to off-hook, dials the tone string (following a successful connection), plays the voice message(s), and resets the hook state to on-hook.

This command has one of the following formats:

Use the following format to play a message from a non-indexed voice file:

ADDRESS VOX "CALLPLAY CHANNEL(channelhandle)
   TONESTRING(tonestring)
   FILE(filename_1[...filename_n])
   FILETYPE(NONINDEX)
   [SYSTEM(sysname)]
   [NAME(CPAparameterset)]
   [RINGS(maxrings)]
   [RETRY(numretries)]
   [WAIT(redialwait)]
   [INTERRUPT(YES|NO)]
   [HOOKSTATE(ONHOOK|OFFHOOK)]
   [PREFIX(varname)]
   [CMDRESP(destination)]"

Use the following format to play a message from a voice word library file:

ADDRESS VOX "CALLPLAY CHANNEL(channelhandle)
  TONESTRING(tonestring)
  FILE(filename)
  FILETYPE(WORDLIB)
  VAR(varname)
  [SYSTEM(sysname)]
  [RINGS(maxrings)]
  [RETRY(numretries)]
  [WAIT(redialwait)]
  [INTERRUPT(YES|NO)]
  [HOOKSTATE(ONHOOK|OFFHOOK)]
  [PREFIX(varname)]
  [CMDRESP(destination)]"

CHANNEL

Specifies the channel handle (channelhandle)-identifying some physical channel-that the GETCHANNEL command returns.

Default: There is no default.

TONESTRING

Specifies the telephone number or other special digits (tonestring) to dial.

Valid characters are: 0 1 2 3 4 5 6 7 8 9 * # a b c d & - , T P M L   I X

FILE

Specifies the name of a voice file or voice word library.

Default: There is no default.

FILETYPE

Specifies the type of voice file to play. Valid values are:

NONINDEX

Specifies a non-indexed voice file.

WORDLIB

Specifies a voice word library.

Note: When specifying FILETYPE (WORDLIB), do not include a file extension on the FILE operand.

Default: NONINDEX

VAR

This operand is required only when specifying a voice word library on the FILETYPE operand.

For a voice word library, code either a REXX regular variable or stem variable. When coding regular variables with the var keyword, only that variable is searched.

With a stem variable, all numeric indexes for this stem will be searched. When coding a stem variable, varname. should follow this format:

varname.0

The number of words in your message.

varname.1 through varname.n

Each variable contains one word from the voice word library.

SYSTEM

(Optional) Specifies the name of the system running the notification server to which you want to direct the command.

The sysname value can contain up to eight alphanumeric characters.

Default: The local system name

NAME

(Optional) Specifies the name of the call progress analysis (CPA) parameter set to use for dialing. CPA set names can be created and configured using the Configuration Manager.

Default: EngineDefault

RINGS

(Optional) Specifies the approximate number of rings to allow before timing out the request and returning a “noanswer” call completion state. The number of rings specified is not an exact count of the actual rings on the telephone, but an estimation of how long the call should wait to get the given rings count.

Default: 4

RETRY

(Optional) Specifies the maximum number of call retries (after the initial call attempt) to establish a connection.

Default: 0

WAIT

(Optional) Specifies the amount of time to wait (in 1/10-second units) before redialing (if you specify the RETRY operand).

Default: 600 (One minute)

INTERRUPT

(Optional) Specifies whether CA Automation Point interrupts a currently playing voice message if it receives a tone digit (that is, if the remote party presses a key on the telephone keypad). Valid values are:

YES

Allows the interruption.

NO

Prevents the interruption.

Default: YES

HOOKSTATE

(Optional) Specifies whether CA Automation Point resets the hook state of the channel to on-hook after playing the voice message. Valid values are:

ONHOOK

Reset the channel to the on-hook state

OFFHOOK

Allow the channel to remain in the off-hook state

Default: OFFHOOK

PREFIX

(Optional) Specifies the name of the REXX stem variable (other than the default name) that contains the return information for the command.

For information about changing the default variable name, see ADDRESS VOX Return Information in this chapter.

Default: VOX.CALLPLAY

CMDRESP

(Optional) Directs return information to a specific destination (destination). For a list of valid destination values, see ADDRESS VOX Return Information in this chapter.

Default: REXX

Return Information:

After the CALLPLAY command executes, it sets the special REXX return code variable RC.

• If the command executes successfully, the RC variable contains a value of zero. Additionally, the VOX.CALLPLAY variable contains the following:
  • CAD-Connection due to cadence break.
  • LPC-Connection due to loop current.
  • PVD-Connection due to Positive Voice Detection.
  • PAMD-Connection due to Positive Answerplay Machine Detection.

  For more details about specific return information, refer to the ATDX_CONNTYPE() function definition in the Dialogic manuals.

  The connection reason is useful when you need to adjust the call progress analysis (CPA) parameters of your voice card using the Configuration Manager to fine-tune your voice application.

  The Dialogic voice software determines the connection reason, but the algorithm is not always perfect.

• If the command does not execute successfully, the RC variable contains one of the following values: 5107, 5109, 5112, 5116, 5117, 5155, 5199, 5204, 5252, 5301, 5302, 5303, 5304, 5305, 5306. (See the Message Reference Guide for further information.) Additionally, the VOX.ERROR variable contains the complete VOX error message, which includes the four-digit return code and complete error message text.

Usage Notes:

Keep the following information in mind when using the CALLPLAY command:

• Instead of issuing the CALL command followed by a PLAY command, we recommend issuing the single CALLPLAY command whenever possible to improve performance.
• You can use the CALLPLAY command to play voice messages over a voice channel connected to an amplified speaker. The TONESTRING operand must contain the access code (tone-digit string) necessary to activate the speaker feature of the system.
• The return information that the CALLPLAY command provides (see PREFIX) indicates why the command was able to establish a connection.
• See Valid Dialing Characters for information on valid DTMF dialing characters.

Example:

The following REXX code illustrates how to use the CALLPLAY command to call a remote party and play one or more voice messages after making contact:

phonenumber = '412-555-2000'
/* Get exclusive access to a voice channel. */
address vox 'getchannel channelnum(1) prefix(handle)'

/* Attempt to reach the "on-call" operator at most three times,*/
/* waiting one minute between each attempt.                    */

address vox 'callplay channel('handle') tonestring('phonenumber') retry(3) wait(600) file('greeting.vox entruid.vox')'

/* Make sure that we are connected to the right person by */
/* verifying the operator's User-ID/PIN combination.      */

address vox 'getdigits channel('handle') count(8) singlestring(yes) prefix(userid)'

address vox 'playgetdigits channel('handle') file(entrpin.vox) singlestring(yes) prefix(pin)'

address vox 'verifyuser userid('userid') pin('pin')'

/* Deliver the message. */

address vox 'play channel('handle') file(message.vox)'

/* Release the voice channel. */

address vox 'releasechannel channel('handle')'