The DuVoice systems can integrate with a variety of property management systems (PMS) via either a serial RS232 interface or a network connection (using TCP/IP). Precise communication protocols—the need for acknowledgment, the use of a checksum and the exact function strings—may vary depending on the protocol used. This document details the standard DuVoice Advanced protocol. Note: This protocol may be listed in DuVoice applications as the DuVoice Advanced protocol.

The following conventions are used throughout this document.

By default, a DV2000 configured for hospitality has one serial port dedicated for communication with a PMS, using the default settings shown in the following table. These settings are configurable within the range of options shown.

If using a TCP/IP network connection instead, use the following setting(s):

The VMS may be configured to use any valid port number. However, to avoid possible conflicts with ports used for standard networking and internet protocols, a port number higher than 1024 should be chosen.

In either case (serial or TCP), select the DuVoice IVMP protocol when configuring the hospitality and PMS settings in the VMS (using the System Configuration application).

When configured for TCP communication, it is assumed that the PMS will be the server and the DV2000 will be the client. At startup, the DV2000 will attempt to connect to the PMS on the specified port number at the specified IP address. Once the connection is made, it will be persistent until the system shuts down. If the connection is lost unexpectedly, the DV2000 will attempt to re-establish the connection periodically.

Packet configuration is the same for both serial and TCP communication. Once the TCP link is established, packet flow is handled the same way as it is over a serial link, including the use of STX, ETX, and a checksum byte. The ENQ-ACK protocol is supported but not required. However, the recipient of a packet is still expected to respond with an ACK.

Room-based vs. Guest-based Architecture

This protocol only supports a room-based architecture; therefore, this document uses the words room and mailbox synonymously (unless otherwise indicated by the context). Although the physical room may have multiple guests occupying it at the same time, there is only one associated mailbox for each room. This means there is no distinction or separation of messages for one guest in the room versus another (i.e., all guests in the room can access all messages in the mailbox). Also, the mailbox can only have a single guest name associated with it (if the PMS supports that feature).

This also means that when the PMS sends a Move Mailbox packet to the VMS, the VMS will automatically check out the original mailbox after copying the messages and other data to the new mailbox. Consequently, even if multiple guests are moving between the two rooms, only one Move Mailbox packet should be sent.

Finally, this also means that any Check In (or Check Out) packets received after a mailbox has already been marked as checked in (or out) will be acknowledged and logged but otherwise ignored. The PMS may send these redundant packets if it chooses (and likely will if it implements the database swap functionality) without worrying that the VMS will be put into an error condition.

The following table lists the standard control codes used by this protocol.

The <BCC> is a 1-byte LRC checksum calculated by taking the ASCII value of the first byte following the <STX> and doing a bitwise XOR on it with each successive byte, up to and including the <ETX>.

For example, given a std::string Buffer containing the full packet, a calculation of the <BCC> might look something like the following (in C++):

int bcc = 0;
for( int idx=1; idx < Buffer.size()-1; idx++)
{
    bcc ^= (int)Buffer[idx];
}

The receiver should then compare its calculated value with the <BCC> transmitted by the sender immediately following the <ETX>. If they match, an <ACK> should be transmitted back to the sender and the packet acted upon; otherwise, a <NAK> should be transmitted and the packet discarded.

This section describes the actual transmission of data between the PMS and the VMS using the control characters described in Control Codes section above.

This protocol uses bi-directional, half-duplex communication. Consequently, to avoid line contention, the PMS is assumed to have primacy in all cases where there is a conflict except when the VMS is in the middle of sending a packet to the PMS (that is, the VMS will not deal with an <ENQ> or <STX> from the PMS until it has transmitted the <BCC> for the packet). The following two subsections will address how this principal is handled in each case.

The enquiry protocol may be used to verify that the system on the other side of the serial link is ready to accept data packets. To use this protocol, the sender would transmit an <ENQ> across the link and wait for an <ACK> from the receiver. If no response is received within the time limit (see the Timing section below), or an invalid response is received, the sender may retransmit the <ENQ> request up to two more times. After three failures, the sender may conclude that the link is not working and may act accordingly (e.g., log an error and/or disable the link).

However, if the VMS receives an <STX> or <ENQ> in response to an <ENQ>, the VMS will defer to the PMS by re-queuing the packet it was going to send and instead handling the query or packet from the PMS.

Use of the enquiry protocol is supported by this protocol but is not required. Both the PMS and the VMS should be able to accept and properly respond to an <ENQ> but should not require the other system to use the protocol even if it is using the protocol itself. This protocol is generally used only with the serial link and not with TCP.

At any time the serial link is idle, the PMS or VMS may transmit a data packet to the other system. This may be preceded by an <ENQ>-<ACK> handshake, as described in the previous section, although that is not required. Every packet must start with an <STX>, end with an <ETX> and be immediately followed by a single-byte checksum (<BCC>) computed as described in the Block Check Character section above.

Upon receipt of a full packet, the system should compute the checksum and compare it to the checksum received from the sender. If the checksums match, an <ACK> should be immediately transmitted back to the sender; otherwise, a <NAK> should be transmitted instead.

If the sender receives a <NAK> in response to the packet it sent, or if it receives no response at all within the Maximum Response Delay time limit, then it may retransmit the packet up to two more times. After 3 failures the sender should either discard or re-queue the message. It may also assume the link is not working and act accordingly (e.g., log an error and/or disable the link).

Note: If the VMS receives an <ENQ> or <STX> in response to a packet it has sent to the PMS, it will immediately handle the enquiry or packet sent by the PMS as appropriate. In doing so, it will assume that the PMS did not handle the message the VMS had sent and will re-queue the packet so it can be sent again at a later time. This deference to the PMS is intended to avoid line contention.

Any time one of the two systems is offline while the other is still running, the possibility exists that the systems will get out of synch. Consequently, this protocol supports the resynchronization request, which allows one system to request that the remote system perform a database swap. Either system may request a resynchronization at any time; typically, such a request would be made at start-up.

When the PMS receives a resynchronization request, it should send a Check In or Check Out packet for each room, with the Sync Flag set to Y. In addition, it may also send a Text Message Notification packet (depending on if the PMS supports the feature). When the VMS receives a resynchronization request, it will send a Message Waiting Status packet for each room.

In addition to performing a database swap upon request, either system may choose to perform a swap on its own initiative at any time. For example, the PMS may be configured to send a Check In or Check Out packet for each room at a specified time (e.g., midnight) every day. This is entirely optional.

Note that for any room that is already checked in, the VMS will <ACK> but otherwise ignore a Check In packet for that room. Likewise, a Check Out packet will be ignored if the VMS has the room already marked as checked out. Text Message Notification packets will only be applied if the room in question is checked in.

This protocol uses two basic timing parameters: the maximum response delay and the maximum time to wait for a packet. On the VMS, both values can be adjusted, but by default it uses the values listed here.

After the sender has completed transmitting an <ENQ> or a full data packet (including checksum), the receiver must respond with either <ACK> or <NAK> within 2 seconds. Otherwise, the sender should assume no response and act accordingly (as described in the Packet Transmission section above).

After the sender has sent an <STX>, it should complete transmission of the full packet (including checksum) within 2 seconds. Otherwise, the receiver should assume the packet is invalid, discard it, and transmit a <NAK> in response.

This section describes the composition and use of all supported data packet types.

All fields are specified using ASCII text, including numeric fields (e.g., a message count of 01 is specified as 0x30 0x31, not as 0x00 0x01). All fields are of variable length and so do not need to be justified or padded in any manner. In the case of message counts, the VMS may pad the values to two digits with a leading zero, but this is not required.

The following table provides an overview of all supported field types, listing the field name, field ID, data type and a brief comment on formatting. Many of these fields may be optional, depending on what features the given PMS supports and/or what features a given installation is configured to use. Refer to the individual packet descriptions for the list of required and optional fields on a per-packet basis.

Packet length is variable but all packets must conform to the same basic layout:

<STX>{<FieldID><FieldData>}~...~{<FieldID><FieldData>}<ETX><BCC>

For example, a simple Check In packet may look like this:

<STX>PI:11~RM:101~GN:Smith, Mary Jane<ETX><BCC>

As the length of each field is also variable, a field separator value is used to mark the end of each field, except the last one (which is marked by the <ETX> character instead). As shown in the Control Codes section, the field separator value is the tilde character: ~.

Since each field is prefixed with a 3-character ID, field order is flexible and optional fields may be omitted if they are not supported by the PMS, or if they represent optional features that are not enabled for a given installation. Although not strictly required, it is recommended that the packet ID field always be listed first in the packet.

The table below provides an overview of all supported packet types. In addition to the packet ID and a brief description, it also shows which packets the PMS can send, which it may expect to receive from the VMS and whether the PMS is required to support the given packet to comply with this specification:

* PMS must be able to absorb these packets and respond with an ACK but may otherwise discard them.

Generally speaking, the PMS should be able to absorb and acknowledge any packet sent by the VMS, without generating an error, even if all it does is discard the packet as unsupported.

Depending on configuration, the VMS may perform any or all of the following tasks upon receipt of a Check Out packet for a valid room: clear all messages (archiving them for a period of time); delete any personal greetings; reset the password; cancel any scheduled wakeup calls; archive the wakeup call log; disable the mailbox from taking messages; change the phone restriction COS; mark the room as dirty; and mark the mailbox as checked out.

If the room specified does not exist, the VMS may send a Bad Mailbox packet back to the PMS or, if configured to do so, it may create the room mailbox and then configure it as being checked out.

Specifies the room number to check out. This field is required.

Specifies the whether or not this packet is part of a database swap. This field is required; however, if it is missing, the packet is assumed to be a realtime packet (as if the flag were set to N).

Check out room 101:

<STX>PI:10~RM:101~SF:N<ETX><BCC>

Database swap check out room 6225:

<STX>PI:10~RM:6225~SF:Y<ETX><BCC>

Upon receipt of a Check In packet for a valid room, the VMS will mark the mailbox as checked in (if it is not already so marked) and enable it to receive messages. Depending on how the VMS is configured, it may also deposit a welcome message in the mailbox.

If the room specified does not exist, the VMS may send a Bad Mailbox packet back to the PMS or, if configured to do so, it may create the room mailbox and then configure it as being checked out.

Specifies the room number to check in. This field is required.

Specifies the whether or not this packet is part of a database swap. This field is required; however, if it is missing, the packet is assumed to be a real-time packet (as if the flag were set to N).

Specifies the full guest name, which may be displayed in relevant GUI applications and may also be passed to the PBX (if supported). This field may contain both the first and last name, but should be formatted with last name first.

The VMS will parse the field by assuming the last name is comprised of every character up to the first comma, space or / character. It will then skip ahead to the first character that is not a space, comma or / and include all subsequent characters (up to the end of the field) as part of the first name. If no space, comma or / is found in the field, then the entire field will be assigned as the last name. Likewise, if the first character is either a space, a comma, or a /, then the remaining characters will be assigned to the first name. Trailing spaces may be truncated. If either name exceeds 19 characters total, it will be truncated to 19 characters. Any titles (e.g., Mr., Dr., Ms., Jr.) should follow the first name, if they are included at all.

This field is optional, but should be included if possible. If not specified, it will use a default name such as: Guest Room xxx (where xxx is the room number).

Specifies the language to be used when the guest logs into the room mailbox to retrieve messages. This is a one- to four-digit numeric value, where 0 means ‘use the default language’ and all other valid values are three- or four-digit numbers. The default language is typically set to 101 (US English) but may be configured on the VMS to any installed language for which a full prompt set is available. The VMS currently can support the following languages, if they have been purchased and installed:

This field is optional. If not specified, the room will be configured to use the default language.

Specifies the new password for the room. It may be either numeric or alphabetic; however, any alphabetic characters will be translated to numbers based on the telephone keypad. That is, the letter ‘A’ (or ‘a’) will be translated to the number 2, as will the letters ‘B’ and ‘C’. For example, the password “SMIT” will be translated to “7648” before it is assigned to the room mailbox. This field is optional. If not specified, the default password 1234 will be assigned instead.

Specifies whether this guest room should be flagged as a VIP. Depending on configuration, the VMS may use the VIP flag to determine how to perform a wakeup call to the guest room. That is, in the case of a VIP the VMS may call the operator and have the operator call the guest rather than calling the guest directly (for non-VIP guest rooms, the VMS will still call the guest itself). If this feature is not enabled, the VIP flag will be stored but will otherwise be ignored. This field is optional. If not specified, it will default to N (that is, disabled).

Specifies a group to which the room is assigned. If the group does not exist on the VMS, it will create the group and then add the room to it.

In the VMS, groups are represented by group mailboxes. A group mailbox contains a single distribution list specifying all rooms that are members of the group. This allows the front desk (or other administrator) to easily send a message to all members of a group by simply leaving a message in the group mailbox. The group mailbox subscriber menu also can be used to schedule a wakeup call for the group; this will result in a wakeup call being scheduled for the same date and time for each room that is a member of the group.

This field is optional. If not specified, the room will not be assigned to any group.

Check in room 101 with default settings, database swap:

<STX>PI:11~RM:101~SF:Y<ETX><BCC>

Check in room 6225 with the guest name, realtime:

<STX>PI:11~RM:6225~SF:N~GN:Smith, John<ETX><BCC>

Check in room 425 with all fields specified:

<STX>PI:11~RM:425~SF:N~GN:Li, Chun~LN:0~PW:1234~VF:Y~GR:552<ETX><BCC>

Upon receipt of a Move packet, the VMS will mark the destination room as checked in, copy all messages from the source to the destination (as well as any scheduled wakeup calls, the text message count, and guest name info, if present), and then check out the source mailbox. If either room specified does not exist, the VMS will send a Bad Mailbox packet back to the PMS for the invalid room (Note: If the source room is not valid, the VMS will not bother to check the validity of the destination room).

Specifies the room number the guest is moving from. This field is required.

Specifies the room number the guest is moving to. This field is required.

Move guest(s) from room 101 to room 120:

<STX>PI:12~RM:101~DR:120<ETX><BCC>

Move guest(s) from room 6225 to room 5114:

<STX>PI:12~RM:6225~DR:5114<ETX><BCC>

Upon receipt of a Text Message Notification for a valid room, the VMS will save the count in the mailbox. If the count is greater than zero, it will light the MWI for the guest phone and, when the guest logs in to the mailbox, it will inform the guest that there is one or more messages waiting at the front desk. If the count is zero (and assuming there are no voice messages in the mailbox), the VMS will turn off the MWI on the guest phone.

Once the text message count has been set to a value greater than zero, the message lamp will remain lit until the VMS receives a Text Message Notification with a count of 0, or a Check Out packet. If the room specified does not exist, the VMS will send a Bad Mailbox packet back to the PMS.

Specifies the room number for which the text message count is being set. This field is required.

Specifies the number of text messages waiting for the guest at the front desk (this may include faxes and/or packages as well). If the PMS treats the text message notification as a flag rather than as a count, specify a value of 1 to turn on the MWI and a value of 0 to turn it off. The VMS only specifies a count (rather than a flag) for display purposes. The actual count is not announced to the guest; they are only told that there is a message waiting for them at the front desk. This field is required.

Set text message count to 1 for room 101:

<STX>PI:13~RM:101~TC:1<ETX><BCC>

Set text message count to 5 for room 101 (effectively the same as setting it to 1):

<STX>PI:13~RM:101~TC:5<ETX><BCC>

Clear the text message count for room 101:

<STX>PI:12~RM:101~TC:0<ETX><BCC>

Upon receipt of a Schedule Wakeup Call packet for a valid room, the VMS will schedule the wakeup call according to the following rules:

1. If the date is today and the time is already past, the wakeup will not be scheduled.
2. If either the date or the time is omitted (but not both), no wakeup will be scheduled.
3. If the both the date and time fields are omitted, the wakeup will be performed immediately.
   Note: The VMS will never send a packet with this format to the PMS; it will always include the

date and time.

1. If the specified time is not a valid time, no wakeup will be scheduled. The wakeup time must be specified using the 24-hour clock notation, with 0000 for midnight (range: 0000 to 2359).
2. If there is already a wakeup call scheduled for the specified date and time, the packet will be acknowledged but no further action will be taken.
3. Multiple wakeup calls per room are supported.

The date and time of the wakeup call is used to uniquely identify each wakeup call for a given room, allowing the PMS to subsequently cancel the wakeup call if it needs to. This is why both fields are required. If both fields are omitted, the wakeup is performed immediately, so the cancel option is not relevant in that case.

* Both fields may be omitted if the wakeup is to be performed immediately.

Specifies the room number for which the wakeup call is being set. This field is required.

Specifies the date on which the wakeup call is to be performed. The full date must be specified in YYYYMMDD format (e.g., 20090901 for September 1, 2009).

This field is required (unless the Wakeup Call Time field is also omitted).

Specifies the time at which the wakeup call is to be performed. The time must be specified in 24-hour format as HHMM (e.g., 2030 for 8:30 p.m.). Midnight is represented as 0000.

This field is required (unless the Wakeup Call Date field is also omitted).

Schedule a wakeup call for room 101 for September 1, 2009 at 7 a.m.:

<STX>PI:14~RM:101~WD:20090901~WT:0700<ETX><BCC>

Schedule a wakeup call for room 2101 for September 2, 2009 at 5:30 p.m.:

<STX>PI:14~RM:2101~WD:20090902~WT:1730<ETX><BCC>

Schedule a wakeup call for room 101 to be peformed immediately.:

<STX>PI:14~RM:101<ETX><BCC>

Invalid packet – no date specified:

<STX>PI:14~RM:101~WT:0700<ETX><BCC>

Invalid packet – no time specified:

<STX>PI:14~RM:101~WD:20090902<ETX><BCC>

The PMS may send this packet any time it desires to know the message waiting status of a given room. Upon receipt of a Query Message Waiting Status packet for a valid room, the VMS will respond with a Message Waiting Status packet.

If the room specified does not exist, the VMS will send a Bad Mailbox packet back to the PMS.

Specifies the room number for which the text message count is being set. This field is required.

Request message count for mailbox 101:

<STX>PI:15~RM:101<ETX><BCC>

Request message count for mailbox 5114:

<STX>PI:15~RM:5114<ETX><BCC>

* May be omitted if Check In only uses the room number field.

The Update Guest Information packet is used to change any or all ancillary fields associated with a checked-in guest room. If the room number given is currently marked as checked out, then an error will be logged and the packet will be discarded. Only fields included in the packet will be updated; all other fields will be left as-is.

If the room specified does not exist, the VMS will send a Bad Mailbox packet back to the PMS.

Specifies the room to be updated. This field is required.

Specifies the full guest name, which may be displayed in relevant GUI applications and may also be passed to the PBX (if supported). This field may contain both the first and last name, but should be formatted with last name first.

The VMS will parse the field by assuming the last name is comprised of every character up to the first comma, space or / character. It will then skip ahead to the next character that is not a space, comma or / and include all subsequent characters (up to the end of the field) as part of the first name. If no space, comma or / is found in the field, then the entire field will be assigned as the last name. Likewise, if the first character is either a space, a comma, or a /, then the remaining characters will be assigned to the first name. Trailing spaces may be truncated.

If either name exceeds 19 characters total, it will be truncated to 19 characters. Any titles (e.g., Mr., Dr., Ms., Jr.) should follow the first name, if they are included at all.

This field is optional. If not specified, the guest name will remain unchanged.

Specifies the language to be used when the guest logs into the room mailbox to retrieve messages. This is a one-, three- or four-digit numeric value, where 0 means ‘use the default language’ and all other valid values are three- or four-digit numbers. The default language is typically set to 101 (US English) but may be configured on the VMS to any installed language for which a full prompt set is available. The VMS currently can support the following languages, if they have been purchased and installed:

This field is optional. If not specified, the language will remain unchanged.

Specifies the new password for the room. It may be either numeric or alphabetic; however, any alphabetic characters will be translated to numbers based on the telephone keypad. That is, the letter ‘A’ (or ‘a’) will be translated to the number 2, as will the letters ‘B’ and ‘C’. For example, the password “SMIT” will be translated to “7648” before it is assigned to the room mailbox.

This field is optional. If not specified, the password will remain unchanged.

Specifies whether this guest room should be flagged as a VIP. Depending on configuration, the VMS may use the VIP flag to determine how to perform a wakeup call to the guest room. That is, in the case of a VIP the VMS may call the operator and have the operator call the guest rather than calling the guest directly (for non-VIP guest rooms, the VMS will still call the guest itself). If this feature is not enabled, the VIP flag will be stored but will otherwise be ignored.

This field is optional. If not specified, the VIP flag will remain unchanged.

Specifies a group to which the room is assigned. If the group does not exist on the VMS, it will create the group and then add the room to it.

In the VMS, groups are represented by group mailboxes. A group mailbox contains a single distribution list specifying all rooms that are members of the group. This allows the front desk (or other administrator) to easily send a message to all members of a group by simply leaving a message in the group mailbox. The group mailbox subscriber menu also can be used to schedule a wakeup call for the group; this will result in a wakeup call being scheduled for the same date and time for each room that is a member of the group.

This field is optional. If not specified, no group assignment will be made.

Specifies whether the guest room phone should have Do Not Disturb (DND) enabled. This feature is PBX-dependent and therefore may not be supported at all installations. Set this field to Y to enable DND and to N to disable DND.

This field is optional. If not specified, the DND status of the phone will remain unchanged.

Change guest name for mailbox 101 to Smith, Mary Jane:

<STX>PI:16~RM:101~GN:Smith, Mary Jane<ETX><BCC>

Change the language for mailbox 5114 to Arabic:

<STX>PI:16~RM:5114~LN:801<ETX><BCC>

Assign guest room 101 to group 7070 and set the VIP flag to Yes:

<STX>PI:16~RM:5114~GR:7070~VF:Y<ETX><BCC>

Enable DND for the guest phone in room 205:

<STX>PI:16~RM:205~DF:Y<ETX><BCC>

Upon receipt of a Set Phone Restriction packet for a valid room, the VMS will signal the PBX to change the status, profile or class of service (as appropriate) for the room’s extension to the specified value. This is only valid for supported PBX systems: Avaya ACM, Avaya IP Office, Panasonic KX-TDA (with TAPI), ShoreTel, Sphere/Univerge and Vodavi (others may be added in the future). The exact meaning of the supported values ultimately depends on what the PBX itself can support.

If the room specified does not exist, the VMS will send a Bad Mailbox packet back to the PMS.

Specifies the room number whose guest phone is to have its restriction status modified. This field is required.

Specifies the restriction level or COS to assign to the guest phone in the given room. The VMS must be configured to map each valid value to the appropriate status value, COS or profile expected by the attached PBX. This must be configured on a per-site basis at installation time. It is not necessary to include all values 0-9; only those supported by the PMS need to be configured.

This field is required.

The following examples assume that a value of 0 means internal only, 1 means local only and 2 means long distance is allowed. The actual meaning of each value must be configured on the VMS to match the PMS.

Set the phone for mailbox 101 to be restricted to internal calls only (i.e., value 0):

<STX>PI:17~RM:101~PR:0<ETX><BCC>

Set the phone for mailbox 5114 to allow unrestricted long distance (i.e., value 2):

<STX>PI:17~RM:5114~PR:2<ETX><BCC>

This packet type allows a scheduled wakeup call to be canceled. Wakeup calls are uniquely identified for a given room by the date and time for which they were scheduled. Consequently, every wakeup- related packet must include the date and time of the wakeup call. All fields are required. The PMS must ACK this packet but may otherwise disregard it if it does not care about wakeup calls scheduled by the VMS.

Field ID Description Type Format Required PI: Packet ID Numeric 18 Yes RM: Room number Numeric 1-10 digits Yes WD: Wakeup call date Numeric YYYYMMDD Yes WT: Wakeup call time Numeric HHMM (24-hour format) Yes

Specifies the room number for which the wakeup call is being canceled. This field is required.

Specifies the date on which the wakeup call is to be performed. The full date must be specified in YYYYMMDD format (e.g., 20090901 for September 1, 2009). This field is required.

Specifies the time at which the wakeup call is to be performed. The time must be specified in 24-hour format as HHMM (e.g., 2030 for 8:30 pm). Midnight is represented as 0000. This field is required.

Cancel a wakeup call for room 101 that was scheduled for September 1, 2009 at 7 am:

<STX>PI:18~RM:101~WD:20090901~WT:0700<ETX><BCC>

Invalid packet – no date or time specified.:

<STX>PI:18~RM:101<ETX><BCC>

Invalid packet – no date specified:

<STX>PI:18~RM:101~WT:0700<ETX><BCC>

Upon receipt of the Remove From Group packet, the VMS will check if the room is a member of the specified group and, if so, remove it from that group.

If the room is not valid, the VMS will respond with a Bad Mailbox packet.

Specifies the room number to remove from the group. This field is required.

Specifies the group from which the room is to be removed. This field is required.

Remove room 101 from group 7070:

<STX>PI:19~RM:101~GR:7070<ETX><BCC>

The VMS will send a Message Waiting Status packet to the PMS any time one of the following occurs:

1. The PMS sends a Query Message Status packet.
2. A voice message is left in the guest room mailbox.
3. The last voice message in the guest room mailbox’s new message queue has been saved or deleted, leaving no new messages.

Events 2 and 3 above will only result in a Message Waiting Status packet if the VMS has been configured to send MWI notifications to the PMS asynchronously.

Specifies the room number whose message count is being reported. This field is required.

Specifies the number of messages in the guest mailbox’s new message queue. If the PMS treats this field as a flag rather than as a count, any value greater than zero equates to ‘yes’ and the value of zero equates to ‘no’. This field is required.

Report message count of 5 new messages for mailbox 101:

<STX>PI:50~RM:101~VC:5<ETX><BCC>

Report that mailbox 101 has no new messages:

<STX>PI:50~RM:101~VC:0<ETX><BCC>

The VMS will send a Maid Status packet to the PMS anytime one of the following occurs:

1. Whenever a maid code is dialed from the room or is received from an administration application.
2. During night maintenance, if the VMS is configured to do so.
3. On check-out, if the VMS is configured to do so.

The VMS can be configured to auto-change the maid status of a room both during nightly maintenance and at check-out. In both cases, it can also be separately configured to send, or not to send, the status change to the PMS. In some cases, the PMS may already auto-change the status in those cases, so while it might be desirable for the VMS to update itself, it may not be necessary to update the PMS.

Specifies the room number whose maid (or room clean) status is being reported. This field is required.

Specifies the maid (or room clean) status of the room. The meaning of each valid value must be configured on the VMS to match the value expected by the PMS, in order for the administration applications on the VMS to display the correct text.

This field is required.

Specifies the an optional maid ID number. This field is optional. The VMS must be configured whether the PMS expects the maid ID, otherwise it will not be included.

Report maid status for mailbox 101:

<STX>PI:51~RM:101~MS:1<ETX><BCC>

Report maid status for mailbox 101 with a maid ID:

<STX>PI:51~RM:101~MS:0~MI:5510<ETX><BCC>

Whenever a wakeup call is successfully completed or if it reaches the maximum number of failed attempts, the VMS will send a Wakeup Call Result packet to the PMS. The packet includes a code that indicates if the wakeup was answered or if it failed; in case of failure, the code may further indicate what condition resulted in failure for the last call attempt.

The PMS may discard this packet if it does not care about wakeup results, but it should at least be able to receive it and respond with an <ACK>.

As with the Schedule Wakeup Call and Cancel Wakeup Call packets, this packet requires that both the date and time of the wakeup call be specified in order to uniquely identify the wakeup call whose result is being reported.

Specifies the room number for which a wakeup call result is being reported. This field is required.

Specifies the scheduled date of the wakeup call. The full date must be specified in YYYYMMDD format (e.g., 20090901 for September 1, 2009).

This field is required.

Specifies the scheduled time of the wakeup call. The time must be specified in 24-hour format as HHMM (e.g., 2030 for 8:30 p.m.). Midnight is represented as 0000.

This field is required.

Specifies the result of the wakeup call. The table below lists the possible result values. Note that not all PBX systems provide enough data for the VMS to distinguish between a busy condition and an RNA condition.

The No Ring result typically means the VMS could not get dialtone or otherwise could not access the line; usually this happens if the physical line is not plugged into the voice port.

This field is required.

Report a successful wakeup call for room 101 that was scheduled for 7 a.m. on September 1, 2009:

<STX>PI:52~RM:101~WD:20090901~WT:0700~WR:A<ETX><BCC>

Report a failed wakeup call, last failure was due to RNA (not answered):

<STX>PI:52~RM:1114~WD:20090902~WT:0530~WR:R<ETX><BCC>

Report a failed wakeup call, last failure was due to a problem with the line:

<STX>PI:52~RM:1114~WD:20090902~WT:0530~WR:N<ETX><BCC>

Whenever the PMS or VMS feels it may be out of synchronization with the other side, such as when restarting after a shutdown, it may request that the other side perform a database swap. A database swap begins with the Sync Start packet and ends with the Sync End packet. Normal message traffic should be suspended during this time, with packets being buffered for later transmission. On receipt of the Sync End packet (or after 1 minute of inactivity on the line), normal packet tramission may resume.

During the database swap, the PMS should send a Check In or Check Out packet for every valid room, (setting the Sync Flag to Y). It may also send a Text Message Notification packet if that feature is supported. The VMS, on the other hand, will send a Message Waiting Status packet for each room.

This packet has no required (or optional) fields except the Packet ID field.

Request that the other side perform a database swap: <STX>PI:90<ETX><BCC>

When performing a database swap (whether by request or asynchronously), begin by sending the Sync Start packet to indicate that a database swap is starting. This also signals a temporary halt to normal packet transmission while the swap is in progress. Normal transmission can recommence on receipt of the Sync End packet, or after 1 minute of inactivity on the line.

This packet has no required (or optional) fields except the Packet ID field.

Request that the other side perform a database swap:

<STX>PI:91<ETX><BCC>

On completing a database swap, the system performing the swap should conclude by sending a Sync End packet. This signals to both sides that normal message transmission may recommence.

This packet has no required (or optional) fields except the Packet ID field.

Request that the other side perform a database swap:

<STX>PI:92<ETX><BCC>

Either side may a poll/keep-alive packet at any time to verify the link is working. This packet should always be acknowledged with an <ACK>. No further processing is required. It is recommended that only one side of the link send the keep-alive message, and only after there has been no input received for a reasonable length time. #@company_HTML@# systems will send the polling message by default but can be configured to not do so if the PMS wishes to handle this itself.

While some protocols send such messages as frequently as once every 10 seconds or so, #@company_HTML@# recommends a more reasonable minimum interval of 30 seconds (with a preference for longer intervals). The advantage of a longer interval is that activity logs do not become quite so full of keep-alive messages and are therefore easier to read when trouble-shooting communication issues.

Polling packet:

<STX>PI:95<ETX><BCC>

Either side may respond to packet containing an invalid room number by sending back a Bad Mailbox packet (after responding to the original packet with an <ACK> as usual). This is for logging and debugging purposes only and the other system is not required to do anything with this packet except respond with an <ACK>.

Specifies the room number that was found to be invalid. This field is required.

Report that mailbox 1234 is not valid (i.e., not found on the system):

<STX>PI:99~RM:1234<ETX><BCC>

pms maid room