Guides

Webhooks: Messages

Webhook notifications for new messages in the Guest Inbox.

Suggest Edits

Guesty's Open API allows you to send various communications-related webhook notifications to your application's notification URL(s).


What Notifications Can I Receive?

Message notifications are sent by Guesty when there are events such as:

  • A new message is received from your Guests or Owners.
  • A new message has been sent within an existing conversation thread to your Guests or Owners.

📘

Identifying the Message Type

You can differentiate between guest and owner messages by referring to the value in the conversationWith field that is included in each webhook payload.


Why Create Message Webhooks?

To receive external notifications when new messages are sent and received, allowing you to manage guest and owner communications, even when you aren't logged into your Guesty dashboard.


Message Received

This webhook is sent whenever a new message is received to your Guests Inbox or Owners Inbox. Learn how to subscribe to this webhook here.


Webhook to Subscribe

reservation.messageReceived


Webhook Payload

Body ParameterData TypeDescription
reservationIdstringConfirmed reservations, booking requests and cancelled reservations only.
conversationobjectThe conversation object.
messageobjectThe message thread.
eventstringreservation.messageReceived

Payload Example

{
    "reservationId": "630f6529fae9050037b01e5e",
    "conversation": {
        "integration": {
            "platform": "manual",
            "_id": "62e17d4270f77500329c613a"
        },
        "meta": {
            "reservations": [
                {
                    "_id": "630f63bf9dcce60032d93a45",
                    "confirmationCode": "Y7QE9JpxW",
                    "checkIn": "2022-10-02T12:00:00.000Z",
                    "checkOut": "2022-10-10T07:00:00.000Z"
                },
                {
                    "_id": "630f6529fae9050037b01e5e",
                    "confirmationCode": "Br8BYZRpo",
                    "checkIn": "2022-10-14T12:00:00.000Z",
                    "checkOut": "2022-10-22T07:00:00.000Z"
                }
            ],
            "guestName": "Moshe Test"
        },
        "language": "en",
        "isRead": true,
        "priority": 10,
        "snoozedUntil": null,
        "_id": "630f63c09dcce60032d93a7f",
        "accountId": "62a8a2be2e53190032102a6e",
        "guestId": "630f63be8203a600352e1508",
        "conversationWith": "Guest",
        "pendingTasks": [],
        "createdAt": "2022-08-31T13:36:00.683Z",
        "thread": [
            {
                "createdAt": "2022-08-31T13:42:11.746Z",
                "attachments": [],
                "_id": "630f6533bb0be20033061af9",
                "module": "email",
                "type": "fromHost",
                "subject": "Message regarding your reservation Br8BYZRpo from Lemonade House",
                "body": "Hi Moshe,\n\nThank you so much for booking with us! We are looking forward to welcoming you to Rodos.\n\nWe will be in contact closer to your arrival day with all of the details you'll need for a smooth check in and a wonderful stay.\n\nIn the meantime please let us know your estimated arrival time, your email and a phone number we can reach you on during your stay just in case.\n\nIf there is anything else on your mind, please let us know and we’d love to assist :)\n\nKind Regards,\n\n",
                "sentAt": "2022-08-31T13:42:11.746Z",
                "cc": [],
                "bcc": [],
                "postId": "630f6533bb0be20033061af9",
                "from": "CS Tier 2 <[email protected]>",
                "to": [
                    "[email protected]"
                ],
                "isAutomatic": true,
                "reservationId": "630f6529fae9050037b01e5e",
                "id": "630f6533bb0be20033061af9"
            }
        ],
        "lastUpdatedFromGuest": "2022-08-31T13:36:00.683Z",
        "readLog": [],
        "lastModifiedAt": "2022-08-31T13:43:36.282Z",
        "__v": 0,
        "subject": "Message regarding your reservation Br8BYZRpo from Lemonade House",
        "lastUpdatedAt": "2022-08-31T13:42:11.746Z",
        "id": "630f63c09dcce60032d93a7f"
    },
    "message": {
        "module": "email",
        "type": "fromGuest",
        "createdAt": "2022-08-31T13:43:36.265Z",
        "from": "[email protected]",
        "to": [
            "[email protected]"
        ],
        "subject": "Re: Message regarding your reservation Br8BYZRpo from Lemonade House",
        "body": "<html><head></head><body><div dir=\"ltr\">Looking forward to it. I should be&#160;arriving around 2PM<br clear=\"all\"><div><div dir=\"ltr\" class=\"gmail_signature\" data-smartmail=\"gmail_signature\"><table border=\"0\" cellpadding=\"0\" cellspacing=\"0\" style=\"width:536px\">\n\t<tbody>\n\t\t<tr>\n\t\t\t<td style=\"width:60px\"><a href=\"https://www.guesty.com/\" target=\"_blank\"><img alt=\"\" border=\"0\" height=\"152\" src=\"https://i.xink.io/Images/Get/G233/l57.png\" width=\"104\"></a></td>\n\t\t\t<td style=\"width:40px\">&#160;</td>\n\t\t\t<td style=\"width:234px\"><br>\n\t\t\t<span style=\"color:#10275b\"><span style=\"font-family:helvetica neue,helvetica,arial,sans-serif\"><span style=\"font-size:16pt\"><strong>Moshe</strong></span><br>\n\t\t\t<span style=\"font-size:11pt\">Tier 2 Tech Lead</span></span><br>\n\t\t\t<br>\n\t\t\t<br>\n\t\t\t<a href=\"https://www.facebook.com/guestycom/\" target=\"_blank\"><img alt=\"\" border=\"0\" height=\"24\" src=\"https://i.xink.io/Images/Get/G233/l96.png\" width=\"24\"></a>&#160;<a href=\"https://twitter.com/Guesty\" target=\"_blank\"><img alt=\"\" border=\"0\" height=\"24\" src=\"https://i.xink.io/Images/Get/G233/l43.png\" width=\"24\"></a>&#160;<a href=\"https://www.linkedin.com/company/guesty\" target=\"_blank\"><img alt=\"\" border=\"0\" height=\"24\" src=\"https://i.xink.io/Images/Get/G233/l13.png\" width=\"24\"></a>&#160;<a href=\"https://www.instagram.com/guestyinc/\" target=\"_blank\"><img alt=\"\" border=\"0\" height=\"24\" src=\"https://i.xink.io/Images/Get/G233/l1.png\" width=\"24\"></a>&#160;<a href=\"https://www.youtube.com/channel/UCeaGcpUM6TaxnOYHeI2CygA\" target=\"_blank\"><img alt=\"\" border=\"0\" height=\"24\" src=\"https://i.xink.io/Images/Get/G233/l8.png\" width=\"24\"></a></span><br>\n\t\t\t&#160;</td>\n\t\t\t<td style=\"width:266px\"><img alt=\"\" border=\"0\" height=\"129\" src=\"https://i.xink.io/Images/Get/G233/f1.gif\" width=\"220\"></td>\n\t\t</tr>\n\t</tbody>\n</table>\n<a href=\"http://www.guestyval.com/\" target=\"_blank\"><img alt=\"\" border=\"0\" height=\"64\" src=\"https://i.xink.io/Images/Get/G233/g8.png\" width=\"530\"></a></div></div><br></div><br></body></html>"
    },
    "event": "reservation.messageReceived"
}

Message Sent

This webhook is sent whenever a new message is sent to a guest from your Guests Inbox, your Owners Inbox, or through the API. Learn how to subscribe to this webhook here.


Webhook to Subscribe

reservation.messageSent


Webhook Payload

Body ParameterData TypeDescription
reservationIdstringConfirmed reservations, booking requests and cancelled reservations only.
conversationobjectThe conversation object.
messageobjectThe message thread.
eventstringreservation.messageSent

Payload Example

{
    "reservationId": "630f6529fae9050037b01e5e",
    "conversation": {
        "meta": {
            "reservations": [
                {
                    "_id": "630f63bf9dcce60032d93a45",
                    "confirmationCode": "Y7QE9JpxW",
                    "checkIn": "2022-10-02T12:00:00.000Z",
                    "checkOut": "2022-10-10T07:00:00.000Z"
                },
                {
                    "_id": "630f6529fae9050037b01e5e",
                    "confirmationCode": "Br8BYZRpo",
                    "checkIn": "2022-10-14T12:00:00.000Z",
                    "checkOut": "2022-10-22T07:00:00.000Z"
                }
            ],
            "guestName": "Moshe Test"
        },
        "guestId": "630f63be8203a600352e1508",
        "language": "en",
        "lastUpdatedFromGuest": "2022-08-31T13:42:01.847Z",
        "integration": {
            "platform": "manual",
            "_id": "62e17d4270f77500329c613a"
        },
        "_id": "630f63c09dcce60032d93a7f",
        "priority": 10,
        "accountId": "62a8a2be2e53190032102a6e",
        "conversationWith": "Guest",
        "createdAt": "2022-08-31T13:42:11.746Z",
        "lastModifiedAt": "2022-08-31T13:42:11.746Z",
        "pendingTasks": [],
        "lastUpdatedAt": "2022-08-31T13:42:11.746Z",
        "thread": [
            {
                "_id": "630f63c08d9fe50031bc09c9",
                "module": "log",
                "type": "fromHost",
                "body": "New guest reservation Y7QE9JpxW confirmed",
                "createdAt": "2022-08-31T13:36:00.787Z",
                "cc": [],
                "bcc": [],
                "postId": "630f63c08d9fe50031bc09c9",
                "to": [],
                "feedback": {}
            },
            {
                "_id": "630f640ebb0be20033060b3c",
                "module": "log",
                "type": "fromHost",
                "body": "Reservation Y7QE9JpxW status changed to awaiting_payment",
                "createdAt": "2022-08-31T13:37:18.570Z",
                "cc": [],
                "bcc": [],
                "postId": "630f640ebb0be20033060b3c",
                "to": [],
                "feedback": {}
            },
            {
                "_id": "630f64198d9fe50031bc0d3f",
                "module": "log",
                "type": "fromHost",
                "body": "Reservation Y7QE9JpxW status changed to confirmed",
                "createdAt": "2022-08-31T13:37:29.383Z",
                "cc": [],
                "bcc": [],
                "postId": "630f64198d9fe50031bc0d3f",
                "to": [],
                "feedback": {}
            },
            {
                "_id": "630f6529bb0be20033061a88",
                "module": "log",
                "type": "fromHost",
                "body": "New guest reservation Br8BYZRpo confirmed",
                "createdAt": "2022-08-31T13:42:01.774Z",
                "cc": [],
                "bcc": [],
                "postId": "630f6529bb0be20033061a88",
                "to": [],
                "feedback": {}
            },
            {
                "_id": "630f652939a3d70034a6cf99",
                "module": "log",
                "type": "fromHost",
                "body": "New guest reservation Br8BYZRpo confirmed",
                "createdAt": "2022-08-31T13:42:01.847Z",
                "cc": [],
                "bcc": [],
                "postId": "630f652939a3d70034a6cf99",
                "to": [],
                "feedback": {}
            },
            {
                "_id": "630f6533bb0be20033061af9",
                "module": "email",
                "type": "fromHost",
                "subject": "Message regarding your reservation Br8BYZRpo from Lemonade House",
                "body": "Hi Moshe,\n\nThank you so much for booking with us! We are looking forward to welcoming you to Rodos.\n\nWe will be in contact closer to your arrival day with all of the details you'll need for a smooth check in and a wonderful stay.\n\nIn the meantime please let us know your estimated arrival time, your email and a phone number we can reach you on during your stay just in case.\n\nIf there is anything else on your mind, please let us know and we’d love to assist :)\n\nKind Regards,\n\n",
                "createdAt": "2022-08-31T13:42:11.746Z",
                "cc": [],
                "bcc": [],
                "postId": "630f6533bb0be20033061af9",
                "from": "CS Tier 2 <[email protected]>",
                "to": [
                    "[email protected]"
                ],
                "isAutomatic": true,
                "reservationId": "630f6529fae9050037b01e5e",
                "feedback": {}
            }
        ],
        "module": "email",
        "type": "fromHost",
        "subject": "Message regarding your reservation Br8BYZRpo from Lemonade House",
        "body": "Hi Moshe,\n\nThank you so much for booking with us! We are looking forward to welcoming you to Rodos.\n...",
        "sentAt": "2022-08-31T13:42:11.746Z",
        "cc": [],
        "bcc": [],
        "postId": "630f6533bb0be20033061af9",
        "from": "CS Tier 2 <[email protected]>",
        "to": [
            "[email protected]"
        ],
        "isAutomatic": true,
        "reservationId": "630f6529fae9050037b01e5e",
        "feedback": {},
        "threadLength": 6,
        "_meta": "{\"reservations\":[{\"_id\":\"630f63bf9dcce60032d93a45\",\"confirmationCode\":\"Y7QE9JpxW\",\"checkIn\":\"2022-10-02T12:00:00.000Z\",\"checkOut\":\"2022-10-10T07:00:00.000Z\"},{\"_id\":\"630f6529fae9050037b01e5e\",\"confirmationCode\":\"Br8BYZRpo\",\"checkIn\":\"2022-10-14T12:00:00.000Z\",\"checkOut\":\"2022-10-22T07:00:00.000Z\"}],\"guestName\":\"Moshe Test\"}",
        "_integration": "{\"platform\":\"manual\",\"_id\":\"62e17d4270f77500329c613a\"}",
        "_pendingTasks": "[]",
        "_thread": "[{\"_id\":\"630f63c08d9fe50031bc09c9\",\"module\":\"log\",\"type\":\"fromHost\",\"body\":\"New guest reservation Y7QE9JpxW confirmed\",\"createdAt\":\"2022-08-31T13:36:00.787Z\",\"cc\":[],\"bcc\":[],\"postId\":\"630f63c08d9fe50031bc09c9\",\"to\":[],\"feedback\":{}},{\"_id\":\"630f640ebb0be20033060b3c\",\"module\":\"log\",\"type\":\"fromHost\",\"body\":\"Reservation Y7QE9JpxW status changed to awaiting_payment\",\"createdAt\":\"2022-08-31T13:37:18.570Z\",\"cc\":[],\"bcc\":[],\"postId\":\"630f640ebb0be20033060b3c\",\"to\":[],\"feedback\":{}},{\"_id\":\"630f64198d9fe50031bc0d3f\",\"module\":\"log\",\"type\":\"fromHost\",\"body\":\"Reservation Y7QE9JpxW status changed to confirmed\",\"createdAt\":\"2022-08-31T13:37:29.383Z\",\"cc\":[],\"bcc\":[],\"postId\":\"630f64198d9fe50031bc0d3f\",\"to\":[],\"feedback\":{}},{\"_id\":\"630f6529bb0be20033061a88\",\"module\":\"log\",\"type\":\"fromHost\",\"body\":\"New guest reservation Br8BYZRpo confirmed\",\"createdAt\":\"2022-08-31T13:42:01.774Z\",\"cc\":[],\"bcc\":[],\"postId\":\"630f6529bb0be20033061a88\",\"to\":[],\"feedback\":{}},{\"_id\":\"630f652939a3d70034a6cf99\",\"module\":\"log\",\"type\":\"fromHost\",\"body\":\"New guest reservation Br8BYZRpo confirmed\",\"createdAt\":\"2022-08-31T13:42:01.847Z\",\"cc\":[],\"bcc\":[],\"postId\":\"630f652939a3d70034a6cf99\",\"to\":[],\"feedback\":{}},{\"_id\":\"630f6533bb0be20033061af9\",\"module\":\"email\",\"type\":\"fromHost\",\"subject\":\"Message regarding your reservation Br8BYZRpo from Lemonade House\",\"body\":\"Hi Moshe,\\n\\nThank you so much for booking with us! We are looking forward to welcoming you to Rodos.\\n\\nWe will be in contact closer to your arrival day with all of the details you'll need for a smooth check in and a wonderful stay.\\n\\nIn the meantime please let us know your estimated arrival time, your email and a phone number we can reach you on during your stay just in case.\\n\\nIf there is anything else on your mind, please let us know and we’d love to assist :)\\n\\nKind Regards,\\n\\n\",\"createdAt\":\"2022-08-31T13:42:11.746Z\",\"cc\":[],\"bcc\":[],\"postId\":\"630f6533bb0be20033061af9\",\"from\":\"CS Tier 2 <[email protected]>\",\"to\":[\"[email protected]\"],\"isAutomatic\":true,\"reservationId\":\"630f6529fae9050037b01e5e\",\"feedback\":{}}]",
        "_cc": "[]",
        "_bcc": "[]",
        "_to": "[\"[email protected]\"]",
        "_feedback": "{}"
    },
    "message": {
        "module": "email",
        "type": "fromHost",
        "subject": "Message regarding your reservation Br8BYZRpo from Lemonade House",
        "body": "Hi Moshe,\n\nThank you so much for booking with us! We are looking forward to welcoming you to Rodos.\n\nWe will be in contact closer to your arrival day with all of the details you'll need for a smooth check in and a wonderful stay.\n\nIn the meantime please let us know your estimated arrival time, your email and a phone number we can reach you on during your stay just in case.\n\nIf there is anything else on your mind, please let us know and we’d love to assist :)\n\nKind Regards,\n\n",
        "createdAt": "2022-08-31T13:42:11.746Z",
        "sentAt": "2022-08-31T13:42:11.746Z",
        "cc": [],
        "bcc": [],
        "postId": "630f6533bb0be20033061af9",
        "from": "CS Tier 2 <[email protected]>",
        "to": [
            "[email protected]"
        ],
        "isAutomatic": true,
        "reservationId": "630f6529fae9050037b01e5e",
        "feedback": {}
    },
    "event": "reservation.messageSent"
}

📘

Best Practice

To reliably absorb new messages and updates upon receipt of a messages webhook, Guesty recommends using the reservation ID from the payload to retrieve the reservation, from which you can obtain the conversation ID to retrieve the messages.

Compare the current conversation object with your stored data to identify the changes.


FAQs


Why is the payload missing the message or conversation ID?

 

This is the expected outcome for inquiries. Use the reservation ID to retrieve the reservation object from which you can obtain the conversation ID to retrieve the messages.


What are the different values of the type field for a message object synced in a message.Received or message.sent webhook?

 

  • fromGuesty is a message sent by a Guesty Communications Service representative (GCS). It's treated the same as fromHost messages.
  • fromThirdParty is usually a guest message, but it is received via a different communication method, like an Airbnb confirmation email or, unidentified by our system, or a sender email.
  • channel is communication with a channel directly, such as a support email from Airbnb (not a guest).
 

Updated 3 months ago