Hospitality Service Center

Vivien Interface V1.02

Voicemail and IVR Interface description

Responsibility and Authority

Issue / Version
Date:
Status:

1.02
May 17, 2012
Released

Copyright 2012, PSE d.o.o.

Copying of this document, or giving it to others, or the use or communication of the contents
thereof, is forbidden without prior written authorization. The copyright notice hereon shall
not constitute or imply publication. All rights are reserved.

HSC V2.6
Vivien InterfaceV1.0

17.5.2012

20/2

HSC V2.6
Vivien InterfaceV1.0

1. Contents
1.

Contents.......................................................................................... 3

2.

General Information ............................................................................ 5

3.

Communication Level .......................................................................... 6

4.

3.1.

TCP/IP Connection ........................................................................ 6

3.2.

Other Issues ................................................................................ 6

Messages ......................................................................................... 7
4.1.

Message Types ............................................................................. 7

4.2.

Message Formats........................................................................... 8

4.2.1.

Simple message format ............................................................ 8

4.2.2.

XML message format ................................................................ 8

4.3.

Message Description ....................................................................... 8

4.3.1.

Message Type: Configuration ...................................................... 9

4.3.2.

Message Type: Link Alive ......................................................... 10

4.3.3.

Message Type: Resynchronization ............................................... 10

4.3.4.

Message Type: Create Mailbox ................................................... 11

4.3.5.

Message Type: Create Mailbox Response ....................................... 11

4.3.6.

Message Type: Update Mailbox .................................................. 12

4.3.7.

Message Type: Update Mailbox Response ...................................... 12

4.3.8.

Message Type: Drop Mailbox ..................................................... 13

4.3.9.

Message Type: Drop Mailbox Response ......................................... 13

4.3.10.

Query Message Count .............................................................. 13

4.3.11.

Message Count ...................................................................... 14

4.3.12.

Forward Messages .................................................................. 14

4.3.13.

Forward Messages Answer ........................................................ 14

4.3.14.

Set Wakeup ......................................................................... 15

4.3.15.

Clear Wakeup ....................................................................... 15

4.3.16.

Wakeup Response .................................................................. 16

4.3.17.

Validate Staff ....................................................................... 16

17.5.2012

20/3

HSC V2.6
Vivien InterfaceV1.0

5.

4.3.18.

Validate Staff Response ........................................................... 17

4.3.19.

Room Status ........................................................................ 17

4.3.20.

Setting Minibar ..................................................................... 18

4.3.21.

Staff Status ......................................................................... 18

4.3.22.

Service Status ...................................................................... 19

4.3.23.

Service Request Answer ........................................................... 19

Restriction ...................................................................................... 20

17.5.2012

20/4

HSC V2.6
Vivien InterfaceV1.0

2. General Information
This document describes the HSC standard VMS/IVR protocol. Implementing this
protocol, your system will be able to provide VMS, wakeup and IVR functionalities for
HSC.
HSC needs the following functionalities from a 3rd party system:
Creating and destroying mailboxes (updating)
Providing information about mailbox content
Requesting wakeup calls through IVR (clearing)
Executing wakeup calls
Setting room status through IVR
Setting employee presence through IVR
Setting service task status through IVR
Setting minibar consumption through IVR
To be able to use the HSC standard protocol your HSC system must be equipped with the
HSC V2.0 Interface for 3rd Party Voicemail-System license (F31505-K19-B25).
This interface is part of the HSC System from the Version 2.0.50.0 (Service Maintenance
Release A) on.

17.5.2012

20/5

HSC V2.6
Vivien InterfaceV1.0

3. Communication Level
HSC can be connected via TCP/IP. Which way is to be used can be set in the HSC in
Administration GUI (Communication/VMS adapter-Wakeup adapter).
After connecting both applications must start the link by providing some configuration
information. (See Configuration Message) To be sure that the connection is open, both
applications can send link alive messages every to indicate the link is not broken.

3.1. TCP/IP Connection

The TCP/IP connection can also be set up in the HSC in Administration GUI
(Communication/VMS adapter-Wakeup adapter). HSC can act as server or as client.
Normally HSC is used as the client. The standard port is 8601.
If HSC is set to be the host and a client is already connected, this client will be
disconnected as soon as a new client tries to connect. Otherwise, if HSC is set to be the
client, it will try to connect cyclically to the host.
A message must begin with an <STX> character and end with an <ETX> character.

3.2. Other Issues

At the moment there are no security arrangements in this interface.

17.5.2012

20/6

HSC V2.6
Vivien InterfaceV1.0

4. Messages
Invalid message types will be discarded with a warning. Invalid parameters in valid
message types will also be discarded with a warning.

4.1. Message Types

Simple format XML format

Purpose

Direction

LS

LinkStart

Configuration

both

LA

LinkAlive

Link Alive

both

DR

Resynchronization

Resynchronization Issues

both

GI

CreateMailboxRequest

Create Mailbox

HSC 3rd party

HI

CreateMailboxResponse

Create Mailbox Answer

3rd party HSC

GC

UpdateMailboxRequest

Update Mailbox

HSC 3rd party

HC

UpdateMailboxResponse

Update Mailbox Answer

3rd party HSC

GO

DropMailboxRequest

Drop Mailbox

HSC 3rd party

HO

DropMailboxResponse

Drop Mailbox Answer

3rd party HSC

MD

GetMessageCount

Query Message Count

HSC 3rd party

ME

MessageCount

Message Count

3rd party HSC

FQ

ForwardRequest

Forward Messages

HSC 3rd party

FR

ForwardResponse

Forward Messages Answer

3rd party HSC

WR

WakeupRequest

Set a Wakeup

both

WC

WakeupClear

Clear a Wakeup

both

WA

WakeupAnswer

Wakeup Response

both

UP

ValidateStaffRequest

Validate Staff

3rd party HSC

UA

ValidateStaffResponse

Validate Staff Response

HSC 3rd party

RE

RoomStatus

Room Status

3rd party HSC

PS

PostingRequest

Setting Minibar

3rd party HSC

SS

StaffStatus

Staff Status

3rd party HSC

RS

ServiceStatus

Service Status

3rd party HSC

PA

PostingResponse

Service Request Answer

HSC 3rd party

17.5.2012

20/7

HSC V2.6
Vivien InterfaceV1.0

4.2. Message Formats

There are two supported message formats in this interface. HSC can automatically
change between message formats. After the 3rd party system has sent its first message,
HSC will answer in the same format. Both message formats use UTF8 character
encoding.

4.2.1. Simple message format

A 2-byte message type is followed by 1-byte separator = |. Each parameter is
described with 2 bytes, the parameter value follows immediately. The parameters are
also separated. There must be a separator after the last parameter. The separator
character will be escaped by two separator characters.
Example: PP|P1KK|P2|

4.2.2. XML message format

Each message is treated as an XML tag, each parameter is an attribute.
Example: <PP P1=KK P2=/>

4.3. Message Description

Types:
L

a positive integer on 63 bit (long)

Nx

numeric, it must have x digits

Nx-y numeric, it must have at least x, at most y digits

ANx-y alphanumeric, it must have at least x, at most y characters
Enum see possible values in description column
*

17.5.2012

see description column

20/8

HSC V2.6
Vivien InterfaceV1.0

4.3.1. Message Type: Configuration

Both sides must send it after opening the connection. First the 3rd party system must
send it to HSC, and then HSC answers it. Both sides can send it again if the configuration
of the system changes.
Simple
format

XML
attribute

MG

multiGuest

Enum Possible values: T true / F false. If set to true, one

extension could have more than one mailbox.
This parameter can only be sent from the 3rd party
system to HSC. If this parameter is not set, the
default is false.

RW

resetWakeup

Enum Possible values: T true / F false. If set to true,

wakeups set through IVR will not be reset. Also no
daily set is possible through IVR.
This parameter can only be sent from the 3rd party
system to HSC. If this parameter is not set, the
default is false.

FN

fullName

Enum Possible values: T true / F false. If set to true,

guest name is provided in a divided form.
This parameter can only be sent from the 3rd party
system to HSC. If this parameter is not set, the
default is false.

RB

validRoomStatus N4

Bitflag for room status. HSC supports 4 types of room

status:
0 Clean
1 Dirty
2 Out of Service
3 Inspected
Which of them is valid can be set in the application.
The 3rd party system receives this as a bitflag.
Example: 1101 Valid types are clean, dirty and
inspected.
Other room states like something and vacant or
something and occupied, will be not supported.
This parameter can only be sent from the HSC to 3rd
party system. This parameter will always be sent.

WT

wakeTimes

Times for executing wakeups. It is a comma

separated list with the following values:
Wakeup call repetition
Wakeup call length in seconds

17.5.2012

Type Description

20/9

HSC V2.6
Vivien InterfaceV1.0
Simple
format

XML
attribute

Type Description
Wakeup call interval in seconds (time between
the end of a attempt and the start of a new
one)
This parameter can only be sent from the HSC to 3rd
party system. This parameter will always be sent.

4.3.2. Message Type: Link Alive

This message can be sent to prove that the connection is still open. It can be sent from
both parties, after receiving it must be acknowledged within 2 minutes with a Link Alive
message or an other message.
This message has no parameters.

4.3.3. Message Type: Resynchronization

It is possible for both sides to request a resynchronization of mailboxes and wakeups. In
a resynchronization HSC sends each Set Wakeup and Create Mailbox message again.
Simple
format

XML
attribute

Type Description

R#

resyncId

RT

resyncType

Enum Possible values: R request / S start / E end.

One side can request a resynchronization with the
type R. This should be answered with a message
with the type S. After this is sent, each Create
Mailbox and Set Wakeup will be a resynchronization
message and may not be treated as a real message.
After each wakeup and mailbox is synchronized, the
session must be ended with a message with the type
E.

17.5.2012

Each message in one resynchronization session must

contain the same session id.

20/10

HSC V2.6
Vivien InterfaceV1.0

4.3.4. Message Type: Create Mailbox

This message must be answered with the message Create Mailbox Response.
Simple
format

XML
attribute

Type Description

B#

boxId

Unique identifier of the mailbox.

EX

extension

N
1-6

The extension where the mailbox should be set up.

The extension of the room. Mandatory.

GL

language

AN
2-5

Mailbox language. Language is provided in ISO codes,

like en.uk or nl.

GN

name

AN
Name of the guest.
0-50 parameter is set to
follows: F/M | title
last name. If set to
first name.

FX

faxnumber

N
0-6

EM

email

AN
Temporary email address of the mailbox. Not
0-50 mandatory. If the parameter is present but empty, it
should be provided from the 3rd party system in the
response.

If the fullName configuration

true, the name is divided as
| first name | middle name |
false, the name is last name,

Virtual fax number. Not mandatory. If the parameter

is present but empty, it should be provided from the
3rd party system in the response.

4.3.5. Message Type: Create Mailbox Response

This message is an answer to the message Create Mailbox.
Simple
format

XML
attribute

Type

Description

B#

boxId

Unique identifier of the mailbox.

AS

result

Enum

Possible values: O ok / F failed. Result of

operation.

FX

faxnumber

N
1-6

Virtual fax number. Provided if an empty value is

provided in the request. If the 3rd party system
cannot support it, it is absent.

EM

email

AN
0-50

Temporary email address of the mailbox Provided if

an empty value is provided in the request. If the 3rd
party system cannot support it, it is absent.

17.5.2012

20/11

HSC V2.6
Vivien InterfaceV1.0

4.3.6. Message Type: Update Mailbox

This message must be answered with the message Update Mailbox Response. The
function Move Guest is also provided by this message.
Simple
format

XML
attribute

Type Description

B#

boxId

Unique identifier of the mailbox.

EX

extension

N
1-6

If a Move Guest is performed, the new extension

should be sent here.

GL

language

AN
2-5

Mailbox language. Language is provided in ISO codes,

like en.uk or nl. Not mandatory.

GN

name

AN
Name of the guest. If the fullName configuration
0-50 parameter is set to true, the name is divided like
following: F/M | title | first name | middle name |
last name. If set to false, the name is last name,
first name. Not mandatory.

FX

faxnumber

N
1-6

EM

email

AN
Temporary email address of the mailbox. Not
0-50 mandatory. If the parameter is present but empty, it
should be provided from the 3rd party system in the
response.

Virtual fax number. Not mandatory. If the parameter

is present but empty, it should be provided from the
3rd party system in the response.

4.3.7. Message Type: Update Mailbox Response

This message is an answer to the message Update Mailbox.
Simple
format

XML
attribute

Type

Description

B#

boxId

Unique identifier of the mailbox.

AS

result

Enum

Possible values: O ok / F failed. Result of

operation.

FX

faxnumber

N
1-6

Virtual fax number. Provided if an empty value is

provided in the request. If the 3rd party system
cannot support it, it is absent.

EM

email

AN
0-50

Temporary email address of the mailbox. Provided if

an empty value is provided in the request. If the 3rd
party system cannot support it, it is absent.

17.5.2012

20/12

HSC V2.6
Vivien InterfaceV1.0

4.3.8. Message Type: Drop Mailbox

This message must be answered with the message Drop Mailbox Response.
Simple
format

XML
attribute

Type

Description

B#

boxId

Unique identifier of the mailbox.

4.3.9. Message Type: Drop Mailbox Response

This message is an answer to the message Drop Mailbox.
Simple
format

XML
attribute

Type

Description

B#

id

Unique identifier of the mailbox.

AS

result

Enum

Possible values: O ok / F failed. Result of

operation.

4.3.10.

Query Message Count

Querying the count of the messages in a mailbox and/or setting the FO-reminder. This
message must be answered with the message Message Count.
Simple
format

XML
attribute

Type

Description

B#

boxId

Unique identifier of the mailbox.

SL

newMessage

AN
0-100

If it is provided, it means HSC wants to set that

there is a message left at the reception. An empty
value means there is no message left at the
reception.
If HSC cannot provide the text of the message only
the fact, that there is a message a . will be sent.
The second text message replaces the first.

17.5.2012

20/13

HSC V2.6
Vivien InterfaceV1.0

4.3.11.

Message Count

This message must be sent if the counts in a mailbox are changed, and if it is requested
by the message Query Message Count.
Simple
format

XML
attribute

Type

Description

B#

boxId

Unique identifier of the mailbox.

ML

lamp

Enum

Possible values: Y on / N off. Flag whether the

message waiting lamp is on or not.

MC

count

Message count. It is comma separated list with

following values: The last four must not be
provided.
heard voicemails
unheard voicemails
read faxes
unread faxes
read text messages
unread text messages

4.3.12.

Forward Messages

Before a guest checks out, and his/her mailbox is to be destroyed, HSC can offer to
forward his/her messages to an external email address. This message must be answered
with the message Forward Messages Response.
Simple
format

XML
attribute

Type

Description

B#

boxId

Unique identifier of the mailbox.

EM

email

AN
1-50

Target email address for forwarding.

4.3.13.

Forward Messages Answer

This message is an answer to the message Forward Messages.

Simple
format

XML
attribute

Type

Description

B#

boxId

Unique identifier of the mailbox.

AS

result

Enum

Possible values: O ok / F failed. Result of

operation.

17.5.2012

20/14

HSC V2.6
Vivien InterfaceV1.0

4.3.14.

Set Wakeup

This message can also be sent in both directions. If it is sent from HSC, it means that a
wakeup call must be executed at the given time on the given extension. In this case no
daily flag will be sent. If it is sent to HSC, it means that a wakeup was requested via IVR
dialog.
If the resetWakeup configuration parameter is set to true, HSC will not resend it to the
3rd party system. In this case HSC does not accept the daily flag from an IVR dialog.
This message must be answered with the message Wakeup Response.
Simple
format

XML
attribute

EX

Type

Description

extension

N
1-6

Extension where the wakeup call is set, or should be

executed.

TI

timestamp

N14

Time of wakeup. Format is YYYYMMDDHHMMSS.

Example: 20050613162355 13th June 2005 4:23:55
pm.

WD

daily

Enum

Possible values: S true / P false. Flag for daily

wakeup.

4.3.15.

Clear Wakeup

This message can also be sent in both directions. If it is sent from HSC it means that a
Wakeup may not be executed at that time on that extension. If it is sent to HSC, it
means that a wakeup was cleared via IVR dialog.
If the resetWakeup configuration parameter is set to true, HSC wont resend it to the 3rd
party system.
This message must be answered with the message Wakeup Response.
Simple
format

XML
attribute

EX
TI

Type

Description

Extension

N
1-6

Extension where the wakeup call is set, or will be

executed.

Timestamp

N14

Time of wakeup. Format is YYYYMMDDHHMMSS.

Example: 20050613162355 13th June 2005 4:23:55
pm.

17.5.2012

20/15

HSC V2.6
Vivien InterfaceV1.0

4.3.16.

Wakeup Response

This message is an acknowledgement of the messages Wakeup Set and Wakeup Clear or
signals the success or failure of a wakeup call.
Simple
format

XML
attribute

EX

Type

Description

extension

N
1-6

Extension where the wakeup call is set or is/was to

be executed.

TI

timestamp

N14

Time of wakeup. Format is YYYYMMDDHHMMSS.

Example: 20050613162355 13th June 2005 4:23:55
pm.

AW

resultWakeup

Enum

Possible values:
OK ok wakeup call successful
NA no answer wakeup call unsuccessful
(no answer)
NL no line wakeup call unsuccessful (no
line technical problem)
BS busy wakeup call unsuccessful
(extension is busy)
RO request ok wakeup call set or clear
ok
RF request failed wakeup call set or
clear failed

4.3.17.

Validate Staff

With this message the 3rd party system can check the given identity pin of an employee.
For setting a status of an employee or a status of a task, the 3 rd party system needs this
information. This message will be answered with the message Validate Staff Response.
Simple
format

XML
attribute

Type

Description

P#

postId

Request identification. This id will be returned in

the answer.

PN

pin

N4

Identity pin given in IVR dialog.

17.5.2012

20/16

HSC V2.6
Vivien InterfaceV1.0

4.3.18.

Validate Staff Response

This message answers to the message Validate Staff.

Simple
format

XML
attribute

Type

Description

P#

postId

Request identification.

S#

staffId

Staff/employee identifier. Must/could be provided

in the following messages:
Room Status
Setting Minibar
Staff Status
Service Status
If the provided pin is invalid, an empty staffId is
returned.

GL

language

AN
2-5

Default language of employee. Language is provided

in ISO codes, like en.uk or nl. Not mandatory.

4.3.19.

Room Status

This message sets the room status. Which types of room status are valid will be set with
the roomStatus configuration parameter at the beginning. This message will be answered
with the message Service Request Answer.
Simple
format

XML
attribute

Type

Description

P#

postId

Request identification. This id will be returned in

the answer.

S#

staffId

Staff/employee identifier. Not mandatory.

EX

extension

N
1-6

Extension from which the call is made or the

extension which belongs to the room whose status
will be set.

RS

roomStatus

Enum

Room status. Possible values are 0-9. Their meanings

can be found in the message Configuration.

17.5.2012

20/17

HSC V2.6
Vivien InterfaceV1.0

4.3.20.

Setting Minibar

This message is for recording minibar consumption. This message will be answered with
the message Service Request Answer.
Simple
format

XML
attribute

Type

Description

P#

postId

Request identification. This id will be returned in

the answer.

S#

staffId

Staff/employee identifier. Not mandatory.

EX

extension

N
1-6

Extension from which the call is made or the

extension which belongs to the room where the
minibar is.

PT

productType

Enum

Product type. It must be filled with MB or

minibar.

M#

productId

N
1-18

Product identifier.

MQ

quantity

N
1-2

Quantity. 1-99

4.3.21.

Staff Status

This message is for recording the presence of employees. This message will be answered
with the message Service Request Answer.
Simple
format

XML
attribute

Type

Description

P#

postId

Request identification. This id will be returned in

the answer.

S#

staffId

Staff/employee identifier. Mandatory.

SS

staffStatus

Enum

Possible values:
0 employee is available
1 employee is not available
2 employee is having a break

17.5.2012

20/18

HSC V2.6
Vivien InterfaceV1.0

4.3.22.

Service Status

This message is for changing the status of a service request (task). This message will be
answered with the message Service Request Answer.
Simple
format

XML
attribute

Type

Description

P#

postId

Request identification. This id will be returned in

the answer.

S#

staffId

Staff / Employee identifier. Mandatory.

TN

taskNumber

AN2-6 Service request (task) identifier. Mandatory.

ST

taskStatus

Enum

4.3.23.

Possible values:
3 service request (task) is accepted
4 service request (task) is rejected
5 service request (task) is done

Service Request Answer

This message answers to the messages Room Status, Setting Minibar, Staff Status and
Service Status.
Simple
format

XML
attribute

Type

Description

P#

postId

Request identification.

AP

resultPosting

Enum

Possible values:
OK ok event ok
WE extension extension is not valid
(belongs a non-valid room)
WS status status is not valid
WF staff staffId is not valid
WT task taskNumber is not valid
WP product productId is not valid

17.5.2012

20/19

HSC V2.6
Vivien InterfaceV1.0

5. Restriction
Currently the following restrictions apply:
Resynchronization is not effective (it is planned in Release 1.1)
Only simple format is effective no XML (it is planned in Release 1.1)

17.5.2012

20/20