SendVoiceMessage

Purpose

Use SendVoiceMessage to send a new message to a mailbox or forward a message to a different mailbox.

Description

The message can be sent either to an individual mailbox, or to all the mailboxes on a distribution list.

The sender is identified by the current Caller: Profile ID (SV20) and Caller: Mailbox - ID (SV32) system variables. SendVoiceMessage will fail if these variables do not identify a valid application profile and mailbox, or if there is no valid message in the workspace. If the caller attempts to send a message via a private distribution list that is not owned by the caller, the message is returned to the caller and not sent to any of the recipients on the list. In the caller's mailbox, the message appears to have been sent from the owner of the list.

The message is stored in the recipient's mailbox as a New message, and is added to the sender's outgoing messages. If the message status is Future (as a result of using the ChangeMessageAttributes with the Future Dated parameter), the message is not sent to the recipient's mailbox until the specified date and time.

If you specify Send via Distribution List, a background process sends the message to the mailboxes on the distribution list. The result returned is always Succeeded. Note that this result indicates only that the process has completed. It is not an indication that the message has arrived successfully.

If the sender requested acknowledgment of the message (using the Receipt Acknowledgment parameter of ChangeMessageAttributes), the message will be sent to the sender's mailbox as a New message when the recipient plays or deletes the message. The Message: Receipt acknowledgment status system variable (SV161) is set to indicate whether the message was listened to or not.

After a message has been retrieved from disk, SendVoiceMessage can be used to forward the message from one mailbox to another. The recipient of a message can forward the message directly to another mailbox or can change the attributes of a message or annotate the message before forwarding. In all cases, the sender information of the forwarded message reflects the forwarder. The sender information of the original message remains unchanged.

For example, if Rick sends a message to Vicki's mailbox, and Vicki then forwards it to Nick, the message in Nick's mailbox will reflect Vicki as the sender. Vicki can also record an annotation to the message before sending it to Nick.

Rick's outgoing messages will include the original message sent to Vicki, but not the annotated message sent by Vicki to Nick (1 outgoing message). Vicki's incoming messages will include the original message sent by Rick; her outgoing messages will include the message sent to Nick (1 incoming, 1 outgoing message). Nick's incoming messages will include the message sent by Vicki (1 incoming message).

Parameters

The parameters for SendVoiceMessage identify the recipient (or recipients) of the message. The parameters are the same for both new messages and messages that are being forwarded.

When the message is sent to an individual mailbox, the parameters are:

Profile ID

Identifies the owner of the mailbox.

Mailbox ID

Identifies the mailbox. Valid values are 1 through 10.

When the message is sent to all the mailboxes on a distribution list, the parameters are:

Profile ID

Identifies the owner of the distribution list.

Mailbox ID

Identifies the mailbox for which the distribution list was created. Valid values are 1 through 10.

Distribution

Identifies the specific distribution list.

Possible results

SendVoiceMessage can have one of the following results:

Succeeded

The message has been sent or forwarded, as specified.

If the action specified that the message is to be sent to a distribution list, this result shows that the request has been received by the background process that sends messages to the mailboxes on the distribution list.

Failed

The voice message could not be sent. This can occur for a number of different reasons, as identified by the System: Action additional information (SV180) system variable. Possible values are:

0

Other: See the error log for more information.

1

Duplicate message: the message has already been sent to the specified destination. Note that certain attributes, for example, the transaction ID, are not keys in the message database, so changes to these will not make it possible to make a new (unique) entry in the database if the message is sent again to the same mailbox.

2

Invalid profile ID: the specified profile ID does not exist.

3

Invalid mailbox ID: the specified mailbox ID does not identify an active mailbox for the destination profile ID

4

Invalid list ID: the specified distribution list does not exist.

5

Access not allowed: the sender of the message does not have access to the specified distribution list (it is a private list belonging to another profile ID).

6

No message: there is no message in the workspace to send.

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.

ASCII syntax

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

1. "TO_MAILBOX"
2. Profile ID
3. Mailbox ID

Or:

1. "VIA_DIST_LIST"
2. Profile ID
3. Mailbox ID
4. Distribution list ID

For example:

label: "Check Edges"
        SendVoiceMessage("TO_MAILBOX", in1_n, in4_s)
          edge EDGE_SM_COMPLETED:       completed
          edge EDGE_SM_FAILED:          failed
        ;
        SendVoiceMessage("VIA_DIST_LIST", in1_n, in4_s, loc4_s);

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