Managing messages¶
This section describes all the possible actions related to messaging between properties and guests after they make a reservation.
Retrieving and confirming retrieval of messages¶
The Messaging API queues messages on the machine account level. Every message is part of a specific conversation, which exists between two participants: Property and Guest. To make best use of this messaging queue you should:
- Retrieve messages from the queue.
- Confirm the successfull retrieval of those messages.
This removes the retrieved messages from the queue. - Follow steps one and two until the queue is empty.
→ If you have missed or lost messages because of an outage or any other issue, you must retrieve those messages with message queries. See searching messages.
TIP: Use a cron job to handle duplicate messages
It is possible that you retrieve messages you have already confirmed. To avoid storing duplicate messages, use a cron job that periodically filters these out.
Retrieving messages¶
GET
https://supply-xml.booking.com/messaging/messages/latestThe GET /messages/latest request enables you to retrieve messages from a message queue on the machine account level. Every request retrieves a maximum of 100 messages.
Response body example¶
The following is a successful response body example:
{
"meta": {
"ruid": "UmFuZG9tSVYkc2RlIyh9YYuVGLmv13PUyJxscfB0hkeHNTLsLGWx80EBzv17yAX3aPO0RTlx5doV49/NRR4qak1qNsDGbilP"
},
"warnings": [],
"data": {
"messages": [
{
"sender": {
"participant_id": "9f6be5fd-b3a8-5691-9cf9-9ab6c6217327",
"metadata": {
"participant_type": "property"
}
},
"timestamp": "2020-08-17T16:54:19.270Z",
"conversation": {
"conversation_type": "reservation",
"conversation_id": "f3a9c29d-480d-5f5b-a6c0-65451e335353",
"conversation_reference": "3812391309"
},
"message_id": "4ad42260-e0aa-11ea-b1cb-0975761ce091",
"content": "Property message 4f523a42-dc9a-40a5-9ab7-fd2db124cd62",
"attachment_ids": [ "522a4d03-bb1b-4e89-af88-e16dd2375d74" ]
},
{
"sender": {
"participant_id": "9f6be5fd-b3a8-5691-9cf9-9ab6c6217327",
"metadata": {
"participant_type": "property"
}
},
"timestamp": "2020-08-17T16:57:09.124Z",
"conversation": {
"conversation_id": "f3a9c29d-480d-5f5b-a6c0-65451e335353",
"conversation_type": "reservation",
"conversation_reference": "3812391309"
},
"message_id": "b011cc40-e0aa-11ea-b928-810a184a831c",
"content": "Property message 53fef484-ec48-487f-acb6-5086ef87da29",
"attachment_ids": []
},
{
"conversation": {
"conversation_id": "f3a9c29d-480d-5f5b-a6c0-65451e335353",
"conversation_type": "reservation",
"conversation_reference": "3812391309"
},
"message_id": "485f18d0-e0ac-11ea-8397-c17827e93026",
"attachment_ids": [],
"content": "Property message 81ec552a-7c13-416e-a58e-937283ab6bfc",
"sender": {
"participant_id": "9f6be5fd-b3a8-5691-9cf9-9ab6c6217327",
"metadata": {
"participant_type": "property"
}
},
"timestamp": "2020-08-17T17:08:34.141Z"
}
],
"ok": true,
"number_of_messages": 3,
"timestamp": "2020-08-18T14:59:26.41"
},
"errors": []
}Response body elements¶
The following table describes the response elements:
| Element | Description | Type | Notes |
|---|---|---|---|
data |
Contains the response object. | object | |
: ok |
Indicates whether the request was successfull. | boolean | |
: timestamp |
Specifies the time of the request. | string | Follows the ISO 8601 standard in UTC: YYYY-MM-DDThh:mm:ss.mmmZ. |
: number_of_messages |
Specifies the number of messages that you retrieved from the message queue. | integer | |
: messages |
Contains the messages that you retrieved from the message queue. | array | |
:: message_id |
Specifies the unique id of a message. | string | |
:: content |
Specifies the content of the message. | string | |
:: timestamp |
Specifies the time when the message was sent. | string | Follows the ISO 8601 standard in UTC: YYYY-MM-DDThh:mm:ss.mmmZ. |
:: reply_to |
Specifies the id of the participant to which the message is sent to. | string | |
:: attachment_ids |
Contains the ids of the attachments, which are part of the message. | array | |
:: sender |
Contains the information related to the participant that sent the message. | object | |
::: participant_id |
Specifies the id of the participant that sent the message. | string | |
::: metadata |
Contains additional information on the participant that sent the message. | object | |
:::: name |
Specifies the name of the participant that sent the message. | string | |
:::: participant_type |
Specifies the type of the participant that sent the message. | string | Possible values are property or GUEST. |
:::: email_alias |
Specifies the email of the participant that sent the message. | string | |
:: conversation |
Contains the information related to the conversation to which the message belongs. | object | |
::: property_id |
Specifies the property id of the property to which the conversation applies. | integer | |
::: conversation_id |
Specifies the id of the conversation. | string | |
::: conversation_reference |
Specifies the id of the reservation to which this conversation applies. | string | |
::: conversation_type |
Specifies the type of the conversation. | string | Possible values: reservation. |
Confirming the retrieval of messages¶
PUT https://supply-xml.booking.com/messaging/messagesThe PUT /messages request enables you to confirm the successfull retrieval of messages, removing those messages from the queue. Therefore this step is necessary to retrieve the remaining messages.
→ If you want to understand the user flow, see retrieving and confirming retrieval of messages.
Query parameters¶
The following table describes the query parameters you must add:
| Element | Description | Type | Required/Optional | Notes |
|---|---|---|---|---|
number_of_messages |
Specifies the amount of messages you want to confirm you retrieved. | integer | required | You can find the value of number_of_messages in the response body when you retrieve latest messages. |
Response body example¶
The following is a successful response body example:
{
"data": {
"ok": true
},
"warnings": [],
"meta": {
"ruid": "UmFuZG9tSVYkc2RlIyh9YYuVGLmv13PUghc+S+Hxf8kDDmE9pIcRJDlql5z0me9U/HXdkK5kNTwJ8bDjF+xIG9WsKhazErNd"
},
"errors": []
}Response body elements¶
The following table describes the response elements:
| Element | Description | Type | Notes |
|---|---|---|---|
ok |
Indicates whether the request was successfull. | boolean |