Intro to messagingCopy link

The Lodging Supply GraphQL API now provides the ability to retrieve and send messages to travelers. Messaging supports back-and-forth messages sent between the traveler and the lodging partner, and it enables connectivity providers to query for message threads (conversations) by property as well as to query for a specific message thread by ID.

In addition, a notification service (also referred to as "webhooks") enables lodging partners to receive real-time notifications for messages sent before, during, and after a traveler’s stay. To receive notifications:

• You must implement the notifications capability and then subscribe to the messaging event types. MessageThreadCreated, MessageReceived, and MessageAttributesUpdated event types are supported and you must subscribe to them all.
• After a reservation is made, a new message thread is created and two notifications are sent to the callback URL: MessageThreadCreated and MessageReceived.
• After that, either party (traveler or partner) can send a message, which adds a message to the reservation's message thread and a MessageReceived notification is sent. As a message's status changes as it moves through moderation, a MessageAttributesUpdated notification is sent.

Finally, the attachment service is provided, which is a separate REST API that partners must implement in order to upload and download message attachments.

Implementation of the messaging capability, notifications capability, and attachment service is mandatory to enable messaging between travelers and partners. After integrating these capabilities, partners can

• Retrieve a message thread (and its messages) by ID, which relies on the messageThread query, passing in the message thread’s ID that was obtained from the webhook notification.

  –OR–

  Retrieve a message by ID, which relies on the message query, passing in the message ID that was included in the webhook notification.

• Add a message to a message thread, which relies on the sendMessage mutation. If the partner wants to send an attachment in the message, the partner must upload the attachment first and reference the attachment ID in the message.

• Upload and download message attachments, which relies on the attachment service.

In addition to this core functionality, partners can

• Retrieve message threads (conversations) for a property, which relies on the messageThreads query, which uses the property’s EID and message thread creation date to retrieve message thread IDs and messages, including message IDs and details. This is useful if a partner needs to build conversation history for a property.

• Retrieve a message thread for a reservation, which uses the reservations query to retrieve the message thread ID associated with a reservation, if you have adopted the reservation management capability. In particular, the messageThreadId field is available in the Reservation object.

• Retrieve all messages for a property, which relies on the messages query and is useful if the messages were not previously retrieved or in the event of message loss.

• Retrieve a message by ID, which relies on the message query to retrieve a message using its ID.

If you have adopted the reservation management capability, you can use the reservation query to retrieve the message thread ID associated with a reservation. In particular, the messageThreadId field has been added to the Reservation object. If you are unfamiliar with GraphQL concepts, such as queries and mutations, read this overview to learn more.

Workflow

After the messaging capability, notifications capability, and attachment service are implemented, the following workflow is possible:

1. A traveler makes a reservation, which creates the message thread, and the MessageThreadCreated webhook notification is sent to the lodging partner. A message is also created, which captures the reservation event, and the MessageReceived notification is also sent.

   Here is an example of the MessageReceived notification, which includes the message ID and Expedia property ID (EID):

   { 
     "notification_id": "63376d68-651a-11ed-9022-0242ac120442", 
     "event_name": "MessageReceived", 
     "creation_time": "2025-08-10T17:13:36.140Z", 
     "payload": { 
       "property_id": 15239779, 
       "message_thread_id": "63676d68-651a-11ed-9022-0242ac120432", 
       "message_id": "63676d68-651a-11ed-9022-0242ac12662", 
       "message_type" : "FREE_TEXT",
       "from_role": "TRAVELER", 
       "reservation_id": "63676d68-651a-11ed-9022-0242ac120882" 
     } 
   } 
   

   After the reservation is created, either party (traveler or partner) can add a message to the message thread.

• If the partner adds a message, they use their software, which relies on the sendMessage mutation and sends the message to the traveler.
• If the traveler sends a message using the message feature at the point of sale, the message is added to the reservation’s message thread and a MessageReceived notification is sent to the partner.

2. Lodging partner retrieves the message using the ID using the message query.

   • Request
   • Response
   • Copy

   1query { 
   2  message(id: "63676d68-651a-11ed-9022-0242ac12662") { 
   3    id 
   4    messageThread { 
   5      id 
   6      property { 
   7        id 
   8      } 
   9      reservationSummary { 
   10        id 
   11        checkOutDate 
   12        checkInDate 
   13      } 
   14      primaryTraveler { 
   15        firstName 
   16        lastName  
   17      } 
   18    } 
   19    body { 
   20      value 
   21    } 
   22    creationDateTimeUtc 
   23    attachments { 
   24      id 
   25      name 
   26      uploadDateTimeUtc 
   27    } 
   28    fromRole 
   29  } 
   30} 

3. If the partner wants to include an attachment with their message to the traveler, partner uploads the attachment and receives the attachment ID in the response. Here is an example:

   • Request
   • Response
   • Copy

   1curl --request POST \ 
   2  --url https://api.expediagroup.com/supply-lodging/v1/files?type=messageThreadId&value=63676d68-651a-11ed-9022-0242ac120432 \ 
   3  --header 'Authorization: Bearer DXqM0WcAvIq2y2tskJ-bpdavLsmb42_rXE6-iudzZU8:WTAL5CBEhgZfkY3kDNEY6qD0fX2jt5mUoisWWQymjOk' \ 
   4  --header 'Content-Type: multipart/form-data' \ 
   5  --form 'content=@C:\Users\rmishra\Documents\ResortOfferings.pdf'  

4. Lodging partner responds to the message using their software (using the sendMessage mutation and the message thread ID in the notification). Here is an example of the mutation:

   • Request
   • Response
   • Copy

   1mutation { 
   2  sendMessage( 
   3    input: {
   4      attachmentIds: [
   5        "f7283ea0-84f5-4997-8b3b-89a797b7efeb"
   6      ],
   7      body: "Thank you for the booking. We've attached our spa menu for your consideration.",
   8      clientMutationId: "c81529c6-5641-11ee-8c99-0242ac120002",
   9      messageThreadId: "63676d68-651a-11ed-9022-0242ac120432"
   10    }
   11  )  
   12  { 
   13    messageId 
   14    clientMutationId
   15  } 
   16}  

5. MessageReceived webhook notification is sent.

Message types

When a message is retrieved, its type can be included in the payload to indicate why the message was sent (type field on the MessageThreadMessage object). Similarly, message type is included in the MessageReceived and MessageAttributesUpdated webhook notifications. The following table lists the possible message types that may be sent.

Implementation details

• Message threads become inactive either three years after the message thread's creation date or one year after the reservation checkout date, whichever is later. Inactive message thread and their messages cannot be replied to.

• When a traveler sends multiple documents in a message (through email or the traveler dashboard), the message will include an attachment ID for each document that the traveler included in the message. A URL to download each attachment is also provided.

• If a reservation includes multiple rooms, a message thread is created for each room in the reservation because each room is assigned its own reservation ID.

• Message attachments are handled through a separate REST API. Multiple file types are supported, and each attachment can be up to 5MB. Each attachment has its own ID, and only one document can be uploaded at a time. Refer to the attachment service reference for details.

• Notifications are not sent when attachments are uploaded. Rather, the partner will receive a notification for a message. The partner can query for that message, and the attachment ID is included in the results.

• To receive notifications, your endpoint must use Transport Layer Security (TLS) 1.2 or 1.3, to provide over-the-wire encryption (HTTPS).

• Be aware that the following information is redacted in messages:

  • Competitor information
  • Credit card information
  • Bank routing numbers
  • IBAN numbers
  • Phone numbers
  • Email addresses
  • Domain names
  • Email addresses
  • URLs (except for these: host.virtualkey.co, o.hmwy.io, t.hmwy.io, homeaway.tumblr.com, facebook.com/homeaway, pinterest.com/homeaway, twitter.com/homeaway, plus.google.com/+homeawaycom, linkedin.com/company/homeaway, instagram.com/homeaway, youtube.com/homeawayvacation)

Limitations and considerations

• Access to this capability is at the connectivity partner level; this means you query by property ID, message thread ID, or message ID, but you cannot query by lodging partner.

• The messaging capability does not support the following at this time:

  • Reservations made through Expedia Partner Solutions (Expedia Affiliate Network) integrations
  • Reservation cancellation or modification requests
  • Cancellation waiver messages (messages that are sent when a lodging partner waives their cancellation policy and allows a traveler to cancel a reservation)
  • Reservations with stay dates completed prior to October 23, 2023, unless a new message is added to the conversation after October 23, 2023

• If the partner sends a message to a guest using a masked email address (outside of the messaging component of EPC), the content of that message is not available in the messageThread query response. A message is added to the message thread that an email was sent, but the email body is not available.

• Throttling is not supported for notifications. When a new event occurs, all notifications are sent to the partner.

Minimum certification requirements

To complete certification for the messaging capability, you must prove that your software can perform the following:

• Retrieve a message thread (and its messages) by ID
• Retrieve message threads (conversations) for a property
• Retrieve a message by ID
• Add a message to a message thread
• Upload message attachments
• Receive real-time notifications when a reservation is made, when a traveler sends a message during or after a their stay, or when a message's status changes as it moves through moderation