v1/get-threads

Params

Name	Type	Requireness	Default value	Description
bookingsUids	string	optional	none	List of comma separated booking UIDs
threadIds	string	optional	none	List of comma separated thread Ids
fromDate	string	optional	none	YYYY-MM-DD Start of the updated period. If only this date is provided, the `toDate` will be automatically set.
toDate	string	optional	none	YYYY-MM-DD End of the updated period. If only this date is provided, the `fromDate` will be automatically set.
page	int	optional	1	Page number for pagination

Description

Retrieve threads with their messages.

Only one parameter of the 3 optional ones will be returned. (bookingsUids / threadIds / fromDate || toDate)

Airbnb image messages list their images in files as {url} items once the images have been copied to storage.

Airbnb messages list their reactions in reactions, and Airbnb threads list the emoji they accept as reactions in supportedReactions.

This endpoint requires the following scope: messaging

Request sample

{
  "fromDate": "2024-11-19",
  "toDate": "2024-11-20",
  "page": 1
}

Response

{
  "data": [
    {
      "threadId": 1033478,
      "platformType": "airgms",
      "platformUserId": "HMSVLQZNSF5SS2XC",
      "hostUid": "HMSVLQZNSF5SS2XC_airgms",
      "platformGuestId": "BHY8E4CPSM8G0SG4WO0KGS40O",
      "guestUid": "BHY8E4CPSM8G0SG4WO0KGS40O_airgms",
      "createDttm": "2024-02-16 05:18:27",
      "updateDttm": "2024-11-20 13:55:28",
      "listingId": "HMSVLR16ZR7RZP8S",
      "listingUid": "HMSVLR16ZR7RZP8S_airgms_HMSVLQZNSF5SS2XC",
      "reservationCode": "DRT1N2BN",
      "bookingUid": "DRT1N2BN_airgms_HMSVLQZNSF5SS2XC",
      "lastMessageDttm": "2024-11-20 13:55:28",
      "messages": [
        {
          "messageId": 1409180597,
          "platformSenderUserId": "HMSVLQZNSF5SS2XC",
          "senderUid": "HMSVLQZNSF5SS2XC_airgms",
          "messageText": "Api test",
          "messageDttm": "2024-11-20 13:55:28",
          "files": [
            {
              "type": "image\/jpeg",
              "name": "gora2.jpg",
              "url": "https:\/\/lh3.googleusercontent.com\/F-zD8J4HOTz-pydfq0W-F9ybPOoFAiRgyduXOqzPgui7gl4XcGM4Tui5XQSG-0xqsAClHgxhk2iwti1aS4LDSSb90M4yMw1Z2dtlaQ=s0",
              "imageId": 1257,
              "templateId": 99839745
            },
            {
              "type": "image\/jpeg",
              "name": "jon.jpg",
              "url": "https:\/\/lh3.googleusercontent.com\/KkgMHwiCyKvTdZpIfuD1zAVZ7oiMFx3Peu2Hsc29xqT3_hAakM19pTbT0m_G7Mf3sAKIsjhD9P-Edr8QjYSpeyA8yjIY2miSqIKc=s0",
              "imageId": 1258,
              "templateId": 99839745
            }
          ],
          "messageType": "host",
          "editedAt": null,
          "deletedAt": null,
          "reactions": []
        },
        {
          "messageId": 1409179135,
          "platformSenderUserId": "HMSVLQZNSF5SS2XC",
          "senderUid": "HMSVLQZNSF5SS2XC_airgms",
          "messageText": "Hello !",
          "messageDttm": "2024-07-18 03:24:42",
          "files": [],
          "messageType": "host",
          "editedAt": null,
          "deletedAt": null,
          "reactions": []
        }
      ],
      "supportedReactions": []
    },
    {
      "threadId": 1033512,
      "platformType": "airbnb",
      "platformUserId": "123456789",
      "hostUid": "123456789_airbnb",
      "platformGuestId": "987654321",
      "guestUid": "987654321_airbnb",
      "createDttm": "2024-11-18 09:12:40",
      "updateDttm": "2024-11-20 10:31:07",
      "listingId": "5550123",
      "listingUid": "5550123_airbnb_123456789",
      "reservationCode": "HM4ZNBQ8TA",
      "bookingUid": "HM4ZNBQ8TA_airbnb_123456789",
      "lastMessageDttm": "2024-11-20 10:31:07",
      "messages": [
        {
          "messageId": 1409176420,
          "platformSenderUserId": "987654321",
          "senderUid": "987654321_airbnb",
          "messageText": "<a href=\"https:\/\/lh3.googleusercontent.com\/Qm7xR2bLc9TnV4yWk8SdHe1ZaG3uUf6Jo0iPlCyEqX5tBnMhVrSjD\" title=\"Click to open large version\" target=\"_blank\"><img src=\"https:\/\/lh3.googleusercontent.com\/Qm7xR2bLc9TnV4yWk8SdHe1ZaG3uUf6Jo0iPlCyEqX5tBnMhVrSjD\" alt=\"\"><\/a>",
          "messageDttm": "2024-11-20 10:31:07",
          "files": [
            {
              "url": "https:\/\/lh3.googleusercontent.com\/Qm7xR2bLc9TnV4yWk8SdHe1ZaG3uUf6Jo0iPlCyEqX5tBnMhVrSjD"
            }
          ],
          "messageType": "guest",
          "editedAt": null,
          "deletedAt": null,
          "reactions": [
            {
              "emoji": "❤️",
              "reactionCreatorUid": "123456789_airbnb",
              "updatedDttm": "2024-11-20 10:35:12"
            }
          ]
        }
      ],
      "supportedReactions": ["😊", "❤️", "👍", "👏", "🤣"]
    }
  ],
  "meta": {
    "page": 1,
    "hasNextPage": false
  }
}

messageType is one of guest, host, self_service_request. A self_service_request is a structured request a Booking.com guest sends through Booking.com's self-service options; it also carries selfServiceTopic, one of the self-service topics, or null when the guest picked none:

{
  "messageId": 1409180612,
  "platformSenderUserId": "1234567890",
  "senderUid": "1234567890_booking",
  "messageText": "We will arrive around 10 am, can we check in early?",
  "messageDttm": "2024-11-20 14:02:11",
  "files": [],
  "messageType": "self_service_request",
  "selfServiceTopic": "checkin",
  "editedAt": null,
  "deletedAt": null
}

A self-service request that is already older than one hour when it is received does not change the thread's updateDttm or lastMessageDttm.

Every message also carries editedAt and deletedAt: the UTC time an Airbnb sender last edited or unsent it, null when that did not happen or for other channels. An edited message holds its new text; an unsent message stays in the list with an empty messageText and empty files:

{
  "messageId": 1409176533,
  "platformSenderUserId": "987654321",
  "senderUid": "987654321_airbnb",
  "messageText": "",
  "messageDttm": "2024-11-20 10:35:02",
  "files": [],
  "messageType": "guest",
  "editedAt": null,
  "deletedAt": "2024-11-20 10:41:19"
}

An edit or unsend does not change the thread's updateDttm, so a fromDate query does not return the thread again; subscribe to the message_updated webhook to learn about it.

When the files of an Airbnb photo message become available, the thread's updateDttm moves, so a fromDate query returns the thread again with the message's files. A photo message that a sync brings in 24 hours or more after it was sent leaves updateDttm as it is.

Every message carries reactions, the list of reactions on it. Each reaction has emoji, reactionCreatorUid (the Airbnb user who reacted, host or guest, as <Airbnb user ID>_airbnb) and updatedDttm (the time Airbnb recorded the reaction, UTC). Every thread carries supportedReactions, the emoji Airbnb accepts as reactions in that thread. Reactions exist on Airbnb threads only; on other threads both lists are empty.

A reaction change leaves the thread's updateDttm and lastMessageDttm as they are, so a fromDate/toDate read does not return the thread for it. To follow reactions, subscribe to the message reactions changed webhook, or read the thread again by threadIds.

v1/get-threads

[ GET ] https://www.igms.com/api/v1/get-threads

Params

Description

Request sample

Response