Overview

A high level control that plays messages from a voice mailbox. It is the main building block for implementing voice mail systems using VBVoice.

Operation

Two types of messages are supported: New and Old. New messages are those that have not yet been heard, or have been saved as new. New messages are converted to Old after they have been heard.

When a call enters a PlayMsgs control, it first plays the number of each type of message (configurable in the EntryGreeting). It then plays the messages in sequence, starting with the new messages (oldest messages first), using the configurable MsgGreeting. The action after each message is configurable to either start playing the next message immediately or to play the OptionsGreeting, allowing the caller to save, delete, forward or skip the message, or to exit. After both new and old messages have been played, the call exits the control. Once a new message has started playing, it is changed to an old message unless the caller selects one of the option digits for Save-as-new, Delete, Skip message, or hangs up before the end of the message.

& Entry Node

This & input can be used to re-enter the control without changing the state of the control. For instance, if digit handling code is inserted into the OptionDigit event, you can jump to a control providing a special menu and actions to the caller, after which the PlayMsgs control can be re-entered in the same state as it was when the call left the control. In this scenario, the EntryGreeting is not played, but the MsgGreeting for the next message is played.

Exit Node 0 (Exit)

This output is used when the PlayMsgs operation terminates normally, either all messages have been played or the caller pressed the exit digit

Exit Node 1 (Digit)

When a digit is pressed for which the PlayMsgs control does not have a valid action, it fires the OptionDigit event. If VB code sets the Accept parameter to True, the call exits out of the Digit output for special handling. The PlayMsgs control can be re-entered through the & input for resumption of message play at the original message, or the file specified by the MsgIndex property if this has been set.

Message Database

The PlayMsgs control uses a directory-based system to identify message files to play. Each box number has a directory in which voice files are stored. Message types (new, old and deleted) are identified by the extension of the file (VNM, VOM, VDM respectively). These types are registered by VBVoice in the registry so that the SNDREC32.EXE wave player application is used to play them. This provides the ability to send the files (or shortcuts to the files) through a mail system to the recipients. Double-clicking on the message then plays it over the sound card.

Message Data

Every file recorded by the Record control can store a Data field within the file. This message data can be retrieved from the file before being played and can be used to modify the greeting, for example. The data is accessible from the MsgData property.

Recording messages for the PlayMsgs control

When recording messages for later playback by the PlayMsgs control, change the file extension from the default WAV to VNM (VBVoice New Message). This extension is used to differentiate message files from Wave files, so that a different Wave player can be used for each type of message, if desired.

When playing voice messages, it's a good idea to use a smaller, faster Wave player such as SNDREC32. Using different extensions allows a different application to be associated with each type of file. The mailbox directory property should contain the directory of the mailbox into which the message should be recorded. In the voicemail example, this directory consists of BOX<mailbox>, where <mailbox> is a 3 digit number entered by the caller, and subsequently validated by a DataFind control.

PlayMsgs Control Example

Use of the PlayMsgs control is shown in the example PlayMsg.

Option Digit Handling

Options digits are controlled by the following properties. Each of these properties is of type vbvDigitMaskConstants.:

DeleteDigit

Marks the current message as deleted. The file is not erased but the file extension is changed to .VDM.

ExitDigit

Causes the call to exit the PlayMsgs control.

FastForwardDigit

Jumps ahead in the message by a configurable amount.

ForwardDigit

Forwards the message to another box.

The system prompts the caller for a mailbox to forward to (the phrase Please enter the box number to forward to in PLAYMSGS.VAP). The number of digits collected is determined by the FwdDigitsLen INI setting. This value can also be set to a variable number by using the FwdDigitsVariable INI setting, in which case the # key or a timeout can be used to terminate the string of digits.

If the mailbox is not valid (no directory exists), the error count is incremented and the OptionsGreeting repeated. The caller is then prompted to record a prefix to the message using the Please record an introduction for this message phrase. If recorded, this is prepended to the new message, which is then put into the destination mailbox directory. The prepended message has a maximum time of 20 seconds.

The Message Data in the original message is copied into the new, forwarded message.

InfoDigit

Plays the InfoGreeting (by default, the time and date of the message).

LouderDigit

Increases the volume of the playback by one increment. There are 20 volume increments, from -10 to +10, each one approximating to a doubling of the volume.

PauseDigit

Pauses playing of the message for up to 10 seconds. Uses the vbvDigitMaskConstants. The pause can be terminated by any digit.

PreviousMsgDigit

Plays the last message from the beginning.

ReviewDigit

Replays the current message from the beginning.

RewindDigit

Jumps back in the message by a configurable amount.

SofterDigit

Decreases the volume of the playback by one increment.

SaveAsNewDigit

Marks the current message as a new, unheard message, by changing the extension of the file to New.

SkipDigit

Skips to the next message. The status of the current message is not changed.

Invalid Digit, No Digit Handling

If an invalid option digit is received, VBVoice first fires the OptionDigit event. In this event, you can use code to exit to a new control using the TakeCall method. This new control can provide custom menus for your caller and when completed, you can re-enter the PlayMsgs control using the & input to resume message processing.

If no action is taken, the error count is incremented and the control plays the InvalidGreeting followed by the OptionsGreeting. If no digits are received, VBVoice increments the error count and plays the NoDigitsGreeting followed by the OptionsGreeting.

When the error count exceeds the maximum error count, VBVoice continues with default error handling.

Prompts Used by the PlayMsgs Control

There are four special greetings used in this control. The VAP file PLAYMSGS.VAP contains some special phrases used by these greetings. The phrases are indexed by position, rather than name, so the order of the phrases should not be changed.

These phrases are:

EntryGreeting

The default entry greeting uses PlayMsgs property NumNewMessages to inform the caller of the number of new messages. The special control name %#this% is used to refer to the control (allowing the default prompt to work regardless of the actual control name).

InfoGreeting

This greeting is played when the caller presses the Info digit, if configured.  The default greeting is the message's date.

InvalidGreeting

Informs the caller that they have pressed an incorrect digit. The InvalidGreeting and the OptionsGreeting are then played again, until the error count is exceeded. The default greeting is That was not a valid entry.

MsgGreeting

This greeting is used to play the message for the first time. The default greeting says: Message one, new <message file>, where the one refers to the index of this message in the list and new refers to its status. The old and new phrases are selected from the PLAYMSGS.VAP file using the MsgType property to index into the file to select the correct phrase.

NoDigitsGreeting

This greeting is played if no digit is pressed during or after OptionsGreeting. The NoDigitsGreeting and the OptionsGreeting is then played again, until the error count is exceeded. The default NoDigitsGreeting greeting is empty.

OptionsGreeting

It generally says: Press 1 to save your message, 2 to save your message as new, 3 to delete your message, 4 to hear the next message, or 8 to exit. This greeting should be changed to match the digit options you have set.

Initial Setup Properties

ClearDigits

(Boolean)

Clears any digits in the digit buffer when the call enters the control.

DisconnectControl

(String)

See Responding to Caller Hangup.

GlobalToneControl

(String)

See Global Tone Handling.

HelpDigitControl

See Help Digit.

IMaxSil

(Integer)

Sets the amount of silence before waiting for an option digit times out and causes the NoDigitsGreeting to be played.

InvalidErrorControl

See Invalid Digit, No Digits, and Silence Timeout.

MailboxDirectory

(String)

Defines the directory where the messages are to be found. Normally this will contain a reference to a mailbox number entered by the caller.

NoDigitsErrorControl

See Invalid Digit, No Digits and Silence Timeout.

RewindSecs

Integer

Number of seconds to rewind the greeting when the RewindDigit is pressed.

SortDescending

Boolean

This property selects the order in which messages are played. Normally the messages are played with the oldest first, however if this property is set to True, the newest messages are played first. This property should be set before the system is started.

WaitForOption

(Boolean)

If set to True, PlayMsgs waits for an option digit after playing each message. If set to False, PlayMsgs plays the next message immediately.

Runtime Properties

GotoNode

(Integer)

This property will transfer a call to another control. See GotoNode.

MsgData

(Channel as Integer) String

The Record control can associate a data string with each message recorded. This data is accessible from the PlayMsgs control for use in greetings etc. See the PlayMsg example for a demo using this property.

MsgFile

(Channel as Integer) String

The filename of the current message. This contains the name of the file last played by the control.

MsgIndex

(Channel as Integer) Integer

The position of the current message in the list. This property is used by the MsgGreeting to vocalize the message number.

MsgType

(Channel as Integer) vbvMsgTypeConstants

The type of the current message - uses the vbvMsgTypeConstants. See vbvMsgTypeConstants. It is used in the MsgGreeting to play either New or Old.

NumNewMessages

(Channel as Integer) Integer

Returns the number of new messages in current mailbox when the control was entered. It does not reflect changes made by the caller while accessing the mailbox. This property is used by the default EntryGreeting to play the number of new messages available.

NumOldMessages

(Channel as Integer) Integer

Returns the number of old messages found in current mailbox when the control was entered. It does not reflect changes made by the caller while accessing the mailbox.

OptionDigit

(Channel as Integer) vbvDigitMaskConstants

This property returns the value of the last option digit pressed. It can be tested in the OptionDigit event or after exit from the control to implement special digit handling.

Methods

TakeCall

This method allows the programmer to override the graphical connections and transfer a call to any other control. See TakeCall.

Events

Disconnect

See Disconnect Event.

Enter, EnterB

See Enter, EnterB Events.

Exit

See Exit Event.

MsgUpdate

Called when the status of a message has changed from, for example, New to Old. MsgType is set to the new status of the message:

1. Old message: 1

2. New message: 2

3. Deleted message: 3

4. Forwarded message: 4 (Filename contains the newly forwarded filename)

OptionDigit

OptionDigit(ByVal Channel as Integer, ByVal Digit as String, Accept as Integer)

This event fires when a digit has been received which does not match any defined option digit. If Accept is set to True, the control exits immediately out the Digit output. Otherwise the digit is treated as invalid. See Invalid digit, No digit handling.

PhraseError

See PhraseError Event.

PlayRequest

See PlayRequest Event.

VoiceError

See VoiceError Event.

PlayMsgs Mailbox, Entry Conditions Page

Mailbox directory

(MailboxDirectory property)

This specifies the directory containing the messages to play. This is generally the same path as used in the Record control to take messages, but without the appended filename.

After playing message

(WaitForOption property)

These options specify whether the PlayMsgs control plays the options greeting and wait for an option digit after each message, or if it starts playing the next message immediately. A digit pressed during the prefix to the message, as set up in the MsgGreeting, is applied to the previous message, not the new one.

For instance, if the default MsgGreeting is used, the first prompt might be:

Message

One (message number)

New (message type)

Hello, this is John. Please call (the actual message)

It starts playing: Message two, new. If the digit 2 (review) is pressed during the Message two, new, the system replays the previous message: Hello, this is John. Please call&.

PlayMsgs Digit Options Page

Play Option Digits

Use these fields to specify the options available to the caller after a message has been played. To disable the option, set to digit to None. The OptionsGreeting should be set to match the options specified. See Option Digit Handling.

Setting Up a Voice Mail System

Taking a Message

Ask for the mailbox for the message and collect it in a GetDigits control.

In the Record control, use the mailbox as a partial directory name - each mailbox has its own directory. Newly recorded message should have the file extension .VNM, for example:

BOX%GetMailBox.Digits%\msg*.vnm

In the PlayMsgs control, use the same path for the message directory (in this case the GetMailBox digits is generally entered in a different control - part of the subscriber menu rather than the main menu, for example:

BOX%GetBox.Digits%\

The mailbox uses the suffixes VNM and VOM respectively for new and old messages. The file date and time is used to order the messages.

Group Boxes

Group boxes may be implemented just by copying a file into each mailbox directory.

See the description of the Voicemail example program.