MyGuest Api
Version 2 of the MyGuest API has been created to allow for interconnecting of our existing services into the MyGuest application by creating endpoints to support the creation, updating and retrieval of requests and can be further expanded as scope requires. Currently the API is designed for internal consumption from other BC services, however endpoints and calls are being written in such a way that they could opened up to third party developers at a later date.
Test and Production
In test, a chron job will run every 5 min if it's not commented out. You can watch the queue at https://adminonline-test.bookingcenter.com/myguest_queue.phtml?port=2. You can see the history at https://adminonline-test.bookingcenter.com/myguest_history.phtml?port=2
Troubleshooting
When a system (System Trigger, MyBooking, AirBnB, etc) places a message to be processed by the API, we view these in the Que | MyGuest Que where we can see about any errors or pending messages. This is the place to verify whether a System placed the correct message in or not.
Once the message is processed, and thus we can verify what took place, we view these in the Logging | MyGuest History.
Authentication:
All endpoints and calls require authentication in the form of a login and key pair that are defined in the MyGuest app under Connected Apps. The api_login can be defined as either a string, or an integer, however the api_key must always be in UUID format.
If the call method is GET it needs to be included in the url string as shown in the following example
https://manage.bookingcenter.com/api/v2/requests/show/2/281?api_login=1123457&api_key=f4f7ca6c-72b7-4b1c-921e-f31243c2b5ce
For all other call methods, it must be included in the request headers
x-api-login: 1123457 x-api-key: f4f7ca6c-72b7-4b1c-921e-f31243c2b5ce
Failure to include valid credentials as described will return a http status code 401 with a response Unauthorized.
Endpoint Routes:
All endpoints are based off the core url of https://manage.bookingcenter.com/api/
Message Structure
Create Request
POST v2/requests/create/{hotelid}
Request Body Parameters within
Parameter | Description |
---|---|
room | Room number assigned to the booking without the siteid. Cannot be null |
booking_id | Primary Booking ID for the request, omitting the siteid. Cannot be null |
details | Details of the request. 2000 characters maximum. |
email | Guest Email . This is the primary key that will be used to match an existing guest or create a new guest in MyGuests |
name | Guest Name |
phone | Guest Primary Phone. Recommended to default to mobile number to support eventual SMS functionality |
rewards_number | Optional field for supporting a hotels rewards or loyalty program. Can be sent as null or omitted if not used. |
message_channel string optional | Used when created a Request related to a messaging API. |
message_thread string optional | Used when created a Request related to a messaging API. Optional field which can be sent as null or omitted if not used. String should match the thread id provided by the OTA for the messaging thread. If used `message_channel` element is required. |
guest_notify | Boolean to determine if we send an email to the guest on new request creation. Accepted values false or true |
form_name | One of "Self Checkin" , "E-Sign" case insensitive. Mapped to form name and category in MyGuests. If not found a new form will be created |
Example Request
{ "request": { "room": "32", "booking_id": "1332025-4X", "details": "credit card declined", "email": "jchieppa@gmail.com", "name": "Joe Banks", "phone": "7075551414", "rewards_number": null, "message_channel": "Airbnb", "message_thread": "597470647", "guest_notify": false, "form_name": "Self Checkin" } }
Example Response
{ "api_version": "2", "status": "Success", "requests": { "id": 308, "room": "32", "details": null, "property_id": 2, "status_id": 1, "created_at": "2019-01-14 23:26:21", "updated_at": "2019-01-14 23:26:21", "category_id": 21, "completed_at": null, "first_time": 1, "staff_id": null, "guest_id": 13, "booking_id": "1332025-4X", "message_channel": "Airbnb", "message_thread": "597470647", "assigned": null, "status": { "id": 1, "name": "New", "created_at": "2014-11-14 02:23:46", "updated_at": "2014-11-14 02:23:46" }, "guest": { "id": 13, "name": "Joe Banks", "email": "jchieppa@gmail.com", "phone": "7075551414", "rewards_number": "0", "created_at": "2018-02-07 10:49:28", "updated_at": "2019-01-11 22:09:36" }, "staff": null, "category": { "id": 21, "name": "Self Checkin", "department_id": 7, "created_at": "2019-01-14 22:21:55", "updated_at": "2019-01-14 22:21:55", "identifier": "21" } } }
MyGuest Message Queue
While the Api endpoints can be called directly (and may eventually be by third party developers) we will be utilizing a queue to process actions and keep a history.
MG_MESSAGES Table Schema
MG_PKEY is a sequence MG_PKEY_SEQ
Name | Nullable | Type |
---|---|---|
MG_PKEY | NOT NULL | NUMBER(22) Primary Key |
MG_TYPE | NUMBER(3) | |
MG_STATUS | NUMBER(3) | |
MG_DATE | DATE | |
MG_CONTENT | VARCHAR2(2000) | |
MG_SIT_FKEY | NOT NULL | VARCHAR2(10) Foreign Key |
MG_BK_OKEY | VARCHAR2(30) |
Status Codes
Code | Useage |
---|---|
0 | Unprocessed |
1 | Processed |
2 | Error |
4 | Locked |
Reserved Types
Type | Action | Service | Request Message Text (<2000 ctrs) | Parent System | MyGuest Action. *note: If Request status was closed, an update will re-open the Request. If there is no Request the API finds, the API creates a new Request. If multiple BKs have open Req Tix, API updates the last one and ignores prior Req tickets of same Type. |
---|---|---|---|---|---|
1 | New Request | Self Checkin Letter Generated | "SMS Self Checkin message queued" | System Triggers for all Arriving Self Checkin BKs and where new BK arrival = today | Create or Update (if multiple 'edits' occur, the Request might already exist) MyBookings has no role in this step. |
2 | Request Updated | Self Checkin Letter Signed | Self Checkin Letter Signed" | MyBooking | Update (what was created in Type=1) |
3 | Request Completed | Self Checkin Booking Checked In | "Self Checkin Booking Checked In" | MyBooking | Set Complete (what was created in Type=1) |
4 | Request Completed | Self Checkin Booking Cancelled | "Self Checkin Booking Cancelled" | MyBooking | Update (what was created in Type=1) |
5 | Request Updated | Self Checkin Booking Edited | Guest Details: "Self Checkin Guest Details Updated" Payment Details: "Self Checkin Booking Edited (CC Info)" | MyBooking | Update (what was created in Type=1) |
6 | Request Updated | Self Checkin Credit Card Declined | MyBooking | Update (what was created in Type=1) | |
7 | New Request | e-Sign Letter Generated | Auto Letters (won't capture same day BK=arrival 'today') | Create | |
8 | Request Completed | e-Sign Letter Signed | MyBooking | Set Complete (what was created in Type=7) | |
9 | Airbnb Incoming Message | Whatever AirBnB sends and the API | Airbnb API | Create or Update | |
10 | Airbnb Outgoing Message | What is placed in the Guest Notes section of the Request | MyGuest | Reply via Airbnb API | |
20 | New Request | Housekeeping Scheduled | Note that Booking: (href to Booking ID) has been booked, prepare for | Auto Letters (won't capture same day BK=arrival 'today') | Create |
21 | Request Updated | Housekeeping Cancelled | The booking was cancelled | Auto Letters (won't capture same day BK=arrival 'today') | Set Complete (what was created in Type=20) |
22 | New Request | Housekeeping Requested | Note that Room: (insert Room ID and Description) needs to be cleaned. | MyPMS | Create |
23 | Request Updated | Housekeeping Request Cancelled | Note that Room: (insert Room ID and Description) needs to be cleaned. | MyPMS | Set Complete (what was created in Type=22) |
24 | Request Updated | Housekeeping Request Completed | Note that Room: (insert Room ID and Description) has been cleaned. | MyPMS | Set Complete (what was created in Type=22) |
30 | New Request | Booking Made | Note the new booking created, Booking: (href to Booking ID) | Auto Letters (won't capture same day BK=arrival 'today') | Create |
31 | Request Updated | Booking Cancelled | Note that Booking: (href to Booking ID) was cancelled. | Auto Letters (won't capture same day BK=arrival 'today') | Create or Update |
32 | Request Updated | Booking Dates Edited | Note that Booking: (href to Booking ID) has edited their stay dates. | Auto Letters (won't capture same day BK=arrival 'today') | Update (what was created in Type=30) |
MyGuest / BookDB Request to Booking Mapping Table
Table Schema
Name | Nullable | Type |
---|---|---|
MGBK_PKEY | NOT NULL | NUMBER(22) Primary Key |
MGBK_REQ_ID | NOT NULL | NUMBER |
MGBK_SIT_FKEY | NOT NULL | VARCHAR2(10) Foreign Key |
MGBK_BK_FKEY | NOT NULL | VARCHAR2(30) Foreign key |