Managing notifications

The Connectivity Notifications Service (CNS) enables you to receive different types of notifications.

This topic explains the following notification types:

Common notification metadata
Updates to payout details
Updates to payout method details
Updates to virtual credit card details
Updates to bank transfer details
Updates to the VCC balance
Updates to VCC fees
Connectivity Partner phishing notification
Newly created messages

Required connection types

You need to be connected with the corresponding connection type related to the notifications you are interested in. The following are the list of supported notification types and the corresponding connection types that you need to be connected with:

Notification type	Connection type
VCC_BALANCE	Reservations
VIRTUAL_CREDIT_CARD_UPDATE	Reservations
PAYOUT_UPDATE	Reservations
BANK_TRANSFER_UPDATE	Reservations
PAYOUT_METHOD_UPDATE	Reservations
VCC_FEES_PAYOUT	Reservations
MESSAGING_API_NEW_MESSAGE	Messaging

Common notification metadata

Irrespective of the notification types, the following elements are common to all the notifications:

Element	Description	Type	Notes
`metadata`	Contains the message metadata.	object	-
> `uuid`	Specifies the notification's unique identifier (UUID).	string	Useful when contacting Connectivity Support Executives to inquire about a given message.
> `type`	Specifies the message type.	enumerated string	Possible values: `PAYOUT_UPDATE`, `PAYOUT_METHOD_UPDATE`, `VIRTUAL_CREDIT_CARD_UPDATE`, `BANK_TRANSFER_UPDATE`,`VCC_BALANCE`, `VCC_FEES_PAYOUT`, `MESSAGING_API_NEW_MESSAGE`.
> `payloadVersion`	Specifies the payload version	string	Current version: 1.0.

Updates to payout details | PAYOUT_UPDATE

CNS pushes these notifications when there are updates to payout details, such as changes in:

Total payout
Commission and charges

The notification message includes property and reservation identifiers. To get all the updates, query the Get payout details endpoint with these identifiers.

Notification message body

The following table describes the elements you can see in the notification payload:

Element	Description	Type	Notes
`metadata`	Contains the message metadata.	object	-
> `uuid`	Specifies the notification's unique identifier (UUID).	string	Useful when contacting Connectivity Support Executives to inquire about a given message.
> `type`	Specifies the message type.	enumerated string	Possible value: `PAYOUT_UPDATE`
> `payloadVersion`	Specifies the payload version	string	Current version: 1.0.
`payload`	Contains the payload body.	object	-
> `timestamp`	Specifies the timestamp in UTC timezone when the notification was triggered.	datetime	Uses ISO-8601 format.
> `propertyId`	Specifies the property ID that the reservation belongs to.	string
> `reservationId`	Specifies the reservation ID where the payout changes apply.	string

Example payload

The following is a notification payload example:

{
    "metadata": {
        "uuid": "FC70575E-ED0E-11EE-B5FA-B675273ACEB0",
        "type": "PAYOUT_UPDATE",
        "payloadVersion": "1.0"
    },
    "payload": {
        "timestamp": "2023-12-10T10:01:322Z",
        "propertyId": 10345,
        "reservationId": 432647264
    }
}

Updates to payout method details | PAYOUT_METHOD_UPDATE

CNS pushes these notifications when there is an update to the payout method. For example, when the property has successfully changed the payout method from virtual credit card to Bank transfer or vice versa.

The notification message includes property and reservation identifiers. To get all the updates, query the Get payout details endpoint with these identifiers.

Notification message body

The following table describes the elements you can see in the notification payload:

Element	Description	Type	Notes
`metadata`	Contains the message metadata.	object	-
> `uuid`	Specifies the notification's unique identifier (UUID).	string	Useful when contacting Connectivity Support Executives to inquire about a given message.
> `type`	Specifies the message type.	enumerated string	Possible value: `PAYOUT_METHOD_UPDATE`
> `payloadVersion`	Specifies the payload version	string	Current version: 1.0.
`payload`	Contains the payload body.	object	-
> `timestamp`	Specifies the timestamp in UTC timezone when the notification was triggered.	datetime	Uses ISO-8601 format.
> `propertyId`	Specifies the property ID that the reservation belongs to.	string
> `reservationId`	Specifies the reservation ID where the payout changes apply.	string

Example payload

The following is a notification payload example:

{
    "metadata": {
        "uuid": "FC70575E-ED0E-11EE-B5FA-B675273ACEB0",
        "type": "PAYOUT_METHOD_UPDATE",
        "payloadVersion": "1.0"
    },
    "payload": {
        "timestamp": "2023-12-10T10:01:322Z",
        "propertyId": 10345,
        "reservationId": 432647264
    }
}

Updates to virtual credit card details | VIRTUAL_CREDIT_CARD_UPDATE

CNS pushes these notifications when there is an update to the virtual credit card details. For example, Notification service can push a notification to your endpoint when there is an update to the current balance or card status.

The notification message includes property, reservation and VCC identifiers. To get all the updates, query the Get VCC payout details endpoint with these identifiers.

Notification message body

The following table describes the elements you can see in the notification payload:

Element	Description	Type	Notes
`metadata`	Contains the message metadata.	object	-
> `uuid`	Specifies the notification's unique identifier (UUID).	string	Useful when contacting Connectivity Support Executives to inquire about a given message.
> `type`	Specifies the message type.	enumerated string	Possible value: `VIRTUAL_CREDIT_CARD_UPDATE`
> `payloadVersion`	Specifies the payload version	string	Current version: 1.0.
`payload`	Contains the payload body.	object	-
> `timestamp`	Specifies the timestamp in UTC timezone when the notification was triggered.	datetime	Uses ISO-8601 format.
> `propertyId`	Specifies the property ID that the reservation belongs to.	string
> `reservationId`	Specifies the reservation ID where the payout changes apply.	string
> `vccId`	Specifies the unique virtual credit card identifier to which the change applies.	string

Example payload

The following is a notification payload example:

{
    "metadata": {
        "uuid": "FC70575E-ED0E-11EE-B5FA-B675273ACEB0",
        "type": "VIRTUAL_CREDIT_CARD_UPDATE",
        "payloadVersion": "1.0"
    },
    "payload": {
        "timestamp": "2023-12-10T10:01:322Z",
        "propertyId": 10345,
        "reservationId": 432647264,
        "vccId": "FC70575E-ED0E-11EE-B5FA-B675273SHDDBC"
    }
}

Updates to bank transfer details | BANK_TRANSFER_UPDATE

CNS pushes these notifications when there is an update to the bank transfer payout details. For example, Notification service can push a notification to your endpoint when there is an update to the bank transfer payout status change.

The notification message includes property and reservation identifiers. To get all the updates, query the Get bank transfer payout details endpoint with these identifiers.

Notification message body

The following table describes the elements you can see in the notification payload:

Element	Description	Type	Notes
`metadata`	Contains the message metadata.	object	-
> `uuid`	Specifies the notification's unique identifier (UUID).	string	Useful when contacting Connectivity Support Executives to inquire about a given message.
> `type`	Specifies the message type.	enumerated string	Possible value: `BANK_TRANSFER_UPDATE`
> `payloadVersion`	Specifies the payload version	string	Current version: 1.0.
`payload`	Contains the payload body.	object	-
> `timestamp`	Specifies the timestamp in UTC timezone when the notification was triggered.	datetime	Uses ISO-8601 format.
> `propertyId`	Specifies the property ID that the reservation belongs to.	string
> `reservationId`	Specifies the reservation ID where the payout changes apply.	string

Example payload

The following is a notification payload example:

{
    "metadata": {
        "uuid": "FC70575E-ED0E-11EE-B5FA-B675273ACEB0",
        "type": "BANK_TRANSFER_UPDATE",
        "payloadVersion": "1.0"
    },
    "payload": {
        "timestamp": "2023-12-10T10:01:322Z",
        "propertyId": 10345,
        "reservationId": 432647264
    }
}

Updates to VCC balance | VCC_BALANCE

CNS pushes these notifications when there is an update to the VCC balance.

Notification message body

The following table describes the elements you can see in the notification payload:

Element	Description	Type	Notes
`metadata`	Contains the message metadata.	object	-
> `uuid`	Specifies the notification's unique identifier (UUID).	string	Useful when contacting Connectivity Support Executives to inquire about a given message.
> `type`	Specifies the message type.	enumerated string	Possible value: `VCC_BALANCE`
> `payloadVersion`	Specifies the payload version	string	Current version: 1.0.
`payload`	Contains the payload body.	object	-
> `updateTimestamp`	Specifies the timestamp in UTC timezone when the balance was updated.	datetime	Uses ISO-8601 format.
> `updateReason`	Specifies the reason for the update. The VCC gets loaded once per booked room.	enumerated string	Possible values: `final_balance_loaded` - Implies that it is a single room reservation and no further events are expected `final_balance_loaded_with_error` `final_balance_loaded_with_warning` `final_balance_loaded_with_error_and_warning` `multi_room_res` - Implies that it is a multi-room reservations and there can be multiple events sent for this reservation.
> `currency`	Specifies the currency of the VCC balance.	string
> `propertyId`	Specifies the property ID that the reservation belongs to.	string
> `reservationId`	Specifies the reservation ID where the payout changes apply.	string
> `vccBalanceAmount`	Specifies the VCC balance amount.	string

Example payload

The following is a notification payload example:

{
    "metadata": {
        "uuid": "FC70575E-ED0E-11EE-B5FA-B675273ACEB0",
        "type": "VCC_BALANCE",
        "payloadVersion": "1.0"
    },
    "payload": {
        "updateTimestamp": "2023-12-10T10:01:322Z",
        "currency": "USD",
        "propertyId": 10345,
        "reservationId": 432647264,
        "vccBalanceAmount": "123.40"
    }
}

Updates to VCC fees | VCC_FEES_PAYOUT

CNS pushes these notifications when there is an update to the VCC fees payout for successfully collected no-show/cancellation fees.

Notification message body

The following table describes the elements you can see in the notification payload:

Element	Description	Type	Notes
`metadata`	Contains the message metadata.	object	-
> `uuid`	Specifies the notification's unique identifier (UUID).	string	Useful when contacting Connectivity Support Executives to inquire about a given message.
> `type`	Specifies the message type.	enumerated string	Possible value: `VCC_FEES_PAYOUT`
> `payloadVersion`	Specifies the payload version	string	Current version: 1.0.
`payload`	Contains the payload body.	object	-
> `updateTimestamp`	Specifies the timestamp in UTC timezone when the balance was updated.	datetime	Uses ISO-8601 format.
> `currency`	Specifies the currency of the VCC balance.	string
> `propertyId`	Specifies the property ID that the reservation belongs to.	string
> `reservationId`	Specifies the reservation ID where the payout changes apply.	string
> `vccBalanceAmount`	Specifies the VCC balance amount.	string

Example payload

The following is a notification payload example:

{
    "metadata": {
        "uuid": "FC70575E-ED0E-11EE-B5FA-B675273ACEB0",
        "type": "VCC_FEES_PAYOUT",
        "payloadVersion": "1.0"
    },
    "payload": {
        "updateTimestamp": "2023-12-10T10:01:322Z",
        "currency": "USD",
        "propertyId": 10345,
        "reservationId": 432647264,
        "vccBalanceAmount": "123.40"
    }
}

Connectivity Partner phishing notification | ACCSEC_PARTNER_PHISHING

Booking.com sends a notification to connectivity partners when they receive a phishing message from any guest.

Notification message body

The following table describes the elements you can see in the notification payload:

Element	Description	Type	Notes
`metadata`	Contains the message metadata.	object	-
> `uuid`	Specifies the notification's unique identifier (UUID).	string	Useful when contacting Connectivity Support Executives to inquire about a given message.
> `type`	Specifies the message type.	enumerated string	Possible value: `ACCSEC_PARTNER_PHISHING`
> `payloadVersion`	Specifies the payload version	string	Current version: 1.0.
`payload`	Contains the payload body.	object	-
> `notificationText`	Descriptive message shown to the user, explaining the reason for the notification or flag.	string	-
> `reservationId`	Specifies the reservation ID.	string	-
> `messageIdLegacy`	Specifies the legacy message ID.	string	-
> `messageId`	Specifies the message ID of the potential phishing message.	string	-

Example payload

The following is a notification payload example:

{
    "metadata": {
        "uuid": "5eadce53-a307-442e-af78-eb99134f5319",
        "type": "ACCSEC_PARTNER_PHISHING",
        "payloadVersion": "1.0"
    },
    "payload": {
        "notificationText": "A message from reservation ID '9991264543' has been flagged as suspicious - please interact with caution.",
        "reservationId": "9991264543",
        "messageIdLegacy": "ea22d860-86ff-11f0-92d4-1ff5b2108399",
        "messageId": "ea0f2950-86ff-11f0-91c6-278aee44c657"
    }
}

Newly created messages | MESSAGING_API_NEW_MESSAGE

Booking.com sends a notification to connectivity partners whenever a new message is created by any participant.

One notification per message

In comparison to the /messages/latest endpoint, these notifications are provider-specific, not machine account-specific. You will receive a notification for a newly created message only once, regardless of how many machine accounts are configured.

Notification message body

The following table describes the elements you can see in the notification payload:

Element	Description	Type	Notes
`metadata`	Contains the message metadata.	object
> `uuid`	Specifies the notification's unique identifier (UUID).	string	Useful when contacting Connectivity Support Executives to inquire about a given message.
> `type`	Specifies the message type.	string	Possible value: `MESSAGING_API_NEW_MESSAGE`.
> `payloadVersion`	Specifies the payload version.	string	Current version: 1.0.
`payload`	Contains the payload body.	object
> `message_id`	Specifies the unique ID of a message.	string
> `message_type`	Specifies the type of the message.	string	Possible values are: - `free_text`: A message composed of plain text. - `email`: An email message. - `automatically_sent_template`: A message automatically sent from a message template configured by the property via the extranet Messaging Preferences page. - `self_service_event`: A structured message for self-service actions. - `request_to_book_event`: A request-to-book event. You can find information on the request status in the `content` field, which denotes the request as expired, accepted by the property, confirmed by the guest or rejected, etc.
> `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
> `content`	Specifies the content of the message.	string
> `attachment_ids`	Contains the IDs of the attachments, which are part of the message.	array
> `attributes`	Contains the message attributes.	object	This object is extensible. To ensure forward compatibility, your implementation should be designed to ignore any unrecognized fields.
>> `self_service_topic`	Contains the self-service topic for messages that represent self-service events.	string	Possible values include: - `checkin` - `checkout` - `change_dates_nr` - `cancel_booking` - `booking_basic_waive_fee` - `parking` - `free_text_parking` - `bed_type` - `extra_crib` - `extra_bed`
>> `template_id`	Contains the identifier of the message template used that was configured by the property via the extranet Messaging Preferences page.	string
>> `template_name`	Contains the name of the message template used that was configured by the property via the extranet Messaging Preferences page.	string
> `sender`	Contains 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 `hotel` or `guest`.
> `conversation`	Contains 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.	string
>> `conversation_id`	Specifies the ID of the conversation.	string
>> `conversation_reference`	Specifies the ID of the reservation or Booking Request Object to which this conversation applies.	string	For conversations with pre-reservation messages, the Booking Request Object `id` serves as the `conversation_reference` until the booking is confirmed.
>> `conversation_type`	Specifies the type of the conversation.	string	Possible values: `reservation` or `request_to_book`.

Example payload

The following is a notification payload example:

{
    "metadata": {
        "uuid": "1f2375d0-8726-11f0-a87c-a90ecaa1410e",
        "type": "MESSAGING_API_NEW_MESSAGE",
        "payloadVersion": "1.0"
    },
    "payload": {
        "message_id": "4ad42260-e0aa-11ea-b1cb-0975761ce091",
        "message_type": "automatically_sent_template",
        "timestamp": "2020-08-17T16:54:19.270Z",
        "reply_to": "890ac339-072a-5bf7-ad33-2fa32f68c3bd",
        "content": "Template message content",
        "attachment_ids": [ "522a4d03-bb1b-4e89-af88-e16dd2375d74" ],
        "attributes": {
            "template_id": "12345",
            "template_name": "Welcome Template"
        },
        "sender": {
            "participant_id": "9f6be5fd-b3a8-5691-9cf9-9ab6c6217327",
            "metadata": {
                "name": "Test Property",
                "participant_type": "hotel"
            }
        },
        "conversation": {
            "property_id": "1383087",
            "conversation_id": "f3a9c29d-480d-5f5b-a6c0-65451e335353",
            "conversation_type": "reservation",
            "conversation_reference": "3812391309"
        }
    }
}

Recovering missed notifications

If your system or Connectivity Notification Service experiences downtime, you may miss notifications regarding newly created messages sent during that period.

To retrieve any messages created during this outage, use the searching messages endpoints. Make sure to query for messages specifying a specific date and time range.

Use Searching messages endpoint as a fallback

Searching messages can be resource intensive and slow. You should only use this method for data recovery and reconciliation. Do not use this endpoint as your primary method to retrieve messages.