Hotel APIs

Connect Hotel Property Management System and Yeastar Cloud PBX via API to achieve automate hotel operations, such as extension management, wake-up service, statistics for call and mini-bar consumption, change of room's clean status, check-out and so on.

Scenario

Generally, most hotels use traditional PBX to offer guests telecommunication service. With independent Hotel Property Management System, staffs have to manually maintain guest data and operation data. It is prone to errors and inefficiency.

With Yeastar Cloud PBX API, you can integrate Hotel Property Management System with PBX. It not only improves the service for guests to enjoy more call operations, but also saves man-hours with a higher degree of operation automation, greatly increasing staffs' productivity and efficiency.

Management for room extensions

When guests check in, the receptionist can associate guests with specific extensions, and assign different extension functions and outbound call permissions to guests of different levels. For receptionist, he/she can identify the caller and provide professional service when receiving a guest call. For guests, they can enjoy telecommunication service from PBX, such as free calls between hotel rooms, voicemail feature and so on.

  • Query extension list
    1. When the receptionist checks room extensions on Hotel Property Management System, the system sends a query request of extension list to API interface.
    2. After receiving the request, PBX sends extension list to Hotel Property Management System. Then the receptionist can check room extensions.

    For API interface, refer to Query Extension List.

  • Update extension settings
    1. The receptionist enters guest’s information on Hotel Property Management System. The system sends an update request of extension settings to API interface, to change extension name to guest name, and assign extension functions according to guest level, such as voicemail and outbound permission of international calls.
    2. After receiving the request, PBX updates extension settings and responds result to Hotel Property Management System.

    For API interface, refer to Modify an Extension.

Wake-up service

According to guest’s room number, date of stay, and wake-up demand, the receptionist can set a personal wake-up call on Hotel Property Management System. The system will place a timely call to guest's extension and play a voice prompt. The operation is simple, and can be applied to room groups once set. With bulk and automate wake-up service, hotels can improve service quality and increase employees' efficiency when tourist groups check in.
  • Add an alarm
    1. On Hotel Property Management System, the receptionist can set the ring method and the room which requires the wake-up service. After setting, the system sends an alarm-setting request to API interface, to set the ring method for specified extension.
    2. After receiving the request, PBX enables an alarm for the specified extension, and responds result to Hotel Property Management System.

    For API interface, refer to add an alarm.

  • Query an alarm
    1. When the receptionist checks alarm settings for specific extension on Hotel Property Management System, the system sends an alarm-query request to API interface.
    2. After receiving the request, PBX sends the corresponding alarm information to Hotel Property Management System, and the receptionist can view the alarm information.

    For API interface, refer to Query an alarm.

  • Update an alarm
    1. When the receptionist updates alarm settings for specific extension on Hotel Property Management System, the system sends an alarm-update request for specific extension to API interface.
    2. After receiving the request, PBX updates the extension’s alarm settings, and responds result to Hotel Property Management System.

    For API interface, refer to Edit an alarm.

  • Delete an alarm
    1. If a guest doesn't need wake-up service any more, the receptionist can delete the alarms. Hotel Property Management System sends an alarm-deletion request for specific extension to API interface.
    2. After receiving the request, PBX deletes the extension’s alarms, and responds result to Hotel Property Management System.

    For API interface, refer to Delete an alarm.

Call statistics

When a guest ends a call, the PBX immediately sends a CDR report to Hotel Property Management System, so that the system can record the guest's call activities in real time.

Statistics for mini-bar consumption

When a guest checks out, the hotel staff can dial mini-bar code on the phone to record the mini-bar consumption, which not only improves work efficiency but also saves waiting time for the guest.
  1. After checking total consumption of mini-bar items, the hotel staff can dial mini-bar code on the phone, and enter item codes and quantities according to voice prompt.
  2. Based on the gathered key information, PBX generates a Keypress Report and sends the report to Hotel Property Management System. Therefore, the guest's total consumption can be recorded automatically and quickly on the system.

DTMF report example

Extension 2003 dials mini-bar code 778, enters item code 123456789, and enters quantity 2.

{
	"action": "DTMF",
	"callid": "1575425107.149",
	"call": [
		{
			"ext": {
				"extid": "203"
			}
		}
	],
	"infos": "778*123456789*2",
	"sn": "369462038851"
}
Set mini-bar operations and voice prompts
Contact Yeastar Support to obtain mini-bar configuration file. In this example, we use extensions_support.conf.
  1. Set operations for mini-bar.
    1. Log in PBX web page, use FTP or SSH to configure operations for room status change.
      • FTP: Upload extensions_support.conf to FTP directory /support/customcfg/.
      • SSH: Go to /ysdisk/support//customcfg/extensions_support.conf, and configure extensions_support.conf.
        [hotelba]
exten = 778,1,NoOp(778)
same = n,Background(product_id)
same = n,Read(digito,,9,,,4)                       // 9-digit item code
same = n,Gotoif($[${LEN(${digito})}>0]?check,1)
same = n,Background(product_id)
same = n,Read(digito,,9,,,4)
same = n,Gotoif($[${LEN(${digito})}>0]?check,1)
same = n,Background(product_id)
same = n,Read(digito,,9,,,4)
same = n,Gotoif($[${LEN(${digito})}>0]?check,1)
same = n,Goto(h,1)                   // hang up if no item ID entries for 3 times
exten = check,1,Macro(productlist,${digito},1)
same = n,Goto(778,2)
exten = h,1,Hangup() 

[macro-productlist]
exten = s,1,Set(product_id=${ARG1})
same = n,Background(product_idc)   // The item ID you entered is 
same = n,SayDigits(${product_id})
same = n,Background(product_num)
same = n,Read(digito,,2,,,4)                      // double-digit quantity,timeout 4s
same = n,Gotoif($[${LEN(${digito})}>0]?num,1)
same = n,Background(product_num)
same = n,Read(digito,,2,,,4)
same = n,Gotoif($[${LEN(${digito})}>0]?num,1)
same = n,Background(product_num)           // If no quantity entries for 2 times, cancel the operation and return
exten = num,1,Set(product_num=${digito})
same = n,Background(product_numc)         //The quantity you entered is     
same = n,SayDigits(${product_num})         //  
same = n,Goto(confirm,1)
exten = confirm,1,Background(confirm)
same = n,Read(digito,,1,,,4)
same = n,Gotoif($[${digito}=1]?yes,1)      //Press 1 to confirm
same = n,Gotoif($[${digito}=*]?778,1)      //Press * to return
same = n,Gotoif($[${digito}=9]?h,1)        //Press 9 to end the call
same = n,Background(vm-goodbye)
exten = yes,1,UserEvent(DtmfEndString,Info: 778*${product_id}*${product_num})   // send DTMF string 
exten = yes,2,Background(success)    //enter success 
exten = h,1,hangup()
  2. Set voice prompt to be played when recording mini-bar items.
    You can use hotel prompts or customize your voice prompt, and upload the file to /ysapps/pbxcenter/var/lib/asterisk/sounds/zh/ via FTP.
    Note: The voice prompt must be in "8K 16Bit mono wav" format. Synthetic speech is allowed.
    Filename Voice message

    confirm.wav

    Press 1 to confirm, press * to cancel and return

    playnum.wav

    The item ID you entered is

    pro_name.wav

    Please enter item ID and quantity

    product_id.wav

    Please enter item ID

    product_idc.wav

    The item ID you entered is

    product_num.wav

    		 Please enter quantity

    product_numc.wav

    The quantity you entered is

    success.wav

    Enter success

Update room's clean status

After cleaning the room, the hotel staff can update the room's clean status by dialing clean code on the phone; the receptionist can check room's clean status in real time.

  1. The hotel staff dials clean code on the phone, and enters status code according to voice prompt.
  2. Based on the gathered key information, PBX generates a Keypress Report and sends the report to Hotel Property Management System. Therefore, the room's clean status can be updated on the system in real time.

Example of room status change

Hotel staff dials 777 on room phone, and presses *01 to set the room's cleaning status to "Clean".
{
	"action": "DTMF",
	"callid": "1530768971.265",
	"ext": {
		"extid": "1002"
	},
	"infos": "777*01"
}
Set operations and voice prompts for room status change
Contact Yeastar Support to obtain configuration file for room status change. In this example, we use extensions_support.conf.
  1. Set operations for room status change.

    Log in PBX web page, use FTP or SSH to configure operations for room status change.

    • FTP: Upload extensions_support.conf to FTP directory /support/customcfg/.
    • SSH: Go to /ysdisk/support//customcfg/extensions_support.conf, configure extensions_support.conf.
      [Local_Default_CallingRules]
include = clean
include = hotelba
[clean]                                     
exten = 777,1,NoOp(777)                     
same = n,Goto(clean-action,play,1)        
                                            
[clean-action]                              
exten = play,1,Background(roomstatus)       
same = n,WaitExten(4)                      
same = n,Goto(h,1)                         
exten = *00,1,Playback(room)                
exten = *00,n,SayDigits(${CALLERID(num)}) 
exten = *00,n,UserEvent(DtmfEndString,Info:777${EXTEN})
exten = *00,n,Playback(uncleaned)  //, set to unclean,bye
exten = *00,n,Hangup()                                   
exten = *01,1,Playback(room)                             
exten = *01,n,SayDigits(${CALLERID(num)})                
exten = *01,n,UserEvent(DtmfEndString,Info:777${EXTEN})  
exten = *01,n,Playback(cleaned)   //,set to clean,bye
exten = *01,n,Hangup()                                   
exten = h,1,Hangup()                                     
exten = i,1,Goto(always-Hangup,h,1)
  2. Set voice prompt to be played when changing room's cleaning status.
    You can use hotel prompts or customize your voice prompt, and upload the file to /ysapps/pbxcenter/var/lib/asterisk/sounds/zh/ via FTP.
    Note: The voice prompt must be in "8K 16Bit mono wav" format. Synthetic speech is allowed.
    Filename Voice message

    cleaned.wav

    Set to clean, bye

    uncleaned.wav

    Set to unclean, bye

    roomstatus.wav

    Please enter room status code

    room.wav

    Room

Check out

When the receptionist performs check-out for a guest, PBX can automatically reset the room's extension settings, such as extension functions, outbound call permissions, voicemail messages, alarms, and call logs. For tourist groups' check-out, this operation can greatly increase the receptionist's work efficiency.

  1. When the receptionist performs check-out for a guest on Hotel Property Management System, the system sends a check-out request to PBX.
  2. After receiving the request, PBX resets extension settings, alarms settings, and call logs, and responds result to Hotel Property Management System.

For API interface, refer toHotel Check Out.