對話解決方案

透過 API 或 pre-built 使用者介面，促進旅客與住宿業者之間的無縫溝通

對話 API

透過「對話 API」，您可以促進旅客 (或代理商) 與住宿供應商之間的無縫溝通。完成整合後，您即可透過 API 擷取飯店、度假租屋及 Vrbo 房源的對話紀錄，並能透過 API 建立及檢視訊息。

此功能可透過 end-to-end API 介面啟用 post-booking 訊息服務。您可以透過將對話嵌入您自有的 traveler-facing 和 agent-facing 工具中，來掌控「front-end」的使用體驗，藉此與旅客建立信任、降低取消率與服務成本，並簡化支援工作流程。

「對話 API」亦支援透過通知進行主題標籤的功能。主題標籤是用以描述訊息內容的單一或 two-word 描述，可協助您自動化支援流程，並確保訊息被導向至正確的管道。

請參閱「附加資源」部分，進一步了解主題標籤與「AI-powered re-marketing」抑制機制。

「對話 API」是唯一支援 Vrbo 房源庫的對話解決方案。

Conversation API 的運作方式

您可以根據需求，將「對話 API」設定為讓旅宿與旅客直接進行訊息交流，或是讓旅宿與您的客服人員進行訊息交流。無論是哪種情況，您都將透過該預訂的「管理預訂」擷取回應，存取「對話 API」連結，然後將對話入口點呈現給旅客或代理商。當供應商發送新訊息時，系統會立即透過「通知」功能通知您。

注意： The Conversation API 並未提供 pre-built 訊息介面體驗。您需要自行建立這項功能，或是將 Conversation API 整合至現有的訊息介面中。

若您需要 pre-built 的使用者介面，請參閱旅宿訊息中心。

透過「管理預訂」檢視預訂

當您透過「管理預訂」API 的「檢索預訂」端點請求預訂詳細資訊時，回應中的 ``conversations 物件將包含一個指向「對話」API 的連結。

>> 進一步了解「管理預訂」API：。

註：某次對話的add-message 連結為 time-bound，該連結將於產生後一小時失效。請務必在每次回應中針對新的連結發起新的 Retrieve 呼叫，而非長期儲存對話連結。

回應中對話連結的範例：

{
  "itinerary_id": "8999989898988",
  "rooms": [
    {
      "id": "926784314"
    }
  ],
  "links": [
    "conversation": {
      "method": "GET",
      "href": "/v3/conversations/1234567890?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
    }
  ]
}

旅客／代理人的 Surface 對話入口

您可以：

請將此連結嵌入您的 traveler-facing 介面中，以便旅客能直接與旅宿傳送或接收訊息。常見的入口頁面包括預訂確認頁面、行程詳情頁面或確認電子郵件。
請參閱「其他資源」以了解最佳實務。
請將該連結嵌入您的代理工具中，以便您的支援團隊能與旅客及住宿業者進行溝通。

訂閱新訊息通知

請在 Rapid Notifications API 中訂閱以下 conversation-related 活動，以便將 supplier-initiated 訊息作為推播通知接收：

itinerary.message.received —當旅宿向需求方／旅客發送新訊息時觸發
itinerary.message.rejected —當旅宿訊息經判定為詐騙或釣魚性質後遭屏蔽時，即觸發此事件。該訊息已被攔截，未能送達。
itinerary.conversation.attachment.success —當旅客或需求夥伴 (作為代理商訊息的一部分) 所傳送的附件已成功上傳並處理完畢時，即觸發此事件
itinerary.conversation.attachment.failure —當附件上傳失敗時觸發

>> 如需進一步了解入職通知的相關資訊，請參閱「通知」頁面。

向物件傳送訊息

「對話 API」會在單一回應中回傳該預訂的完整訊息紀錄，其中包含旅客／代理商所發送的訊息，以及來自旅宿的回覆。旅宿的訊息可能包含附件及用於存取這些附件的連結。可接受的附件類型包括 PNG、PDF、JPEG 及 DOCX。

該回應中也包含用於傳送訊息的連結：一個是純文字連結，另一個則是用於啟動附件上傳的連結。

傳送純文字訊息

若要發起新訊息或回覆旅宿，請使用add_message 這個連結，在對話中新增一則訊息。成功的回應會傳回一個已更新的對話連結，您應將其儲存起來，並在下次讀取時使用，以確保您的令牌狀態保持最新。

當代理商代表旅客發送訊息時，無論是在 API 中，還是傳送至旅宿頻道，該訊息都會顯示為由旅客本人發送。若代理商希望表明該訊息是由代理商發送的，可加入如下註記：「由 [合作夥伴] 代理商代表旅客發送。」

傳送附件

附件會直接上傳至 Amazon S3。此流程始於對「附件 API」的請求，該請求包含檔案元資料，並可選擇性地包含隨附的訊息內容。此回應會傳回一個受保護的 S3 URL、其有效期限，以及 AWS 所需的表單欄位。支援的檔案類型包括 PNG、PDF 和 JPEG。

註：。此呼叫中提供的文字會隨檔案上傳一併傳送，並在檔案送達時作為訊息內容顯示。因此，無需另外呼叫add_message——若執行此呼叫，將會在該執行緒中產生重複的訊息。

在受保護的 S3 URL 過期之前，請使用先前 Attachments API 回應中提供的表單欄位，將檔案以 POST 方式傳送至該 URL。

>> 詳情請參閱 AWS 文件。

成功的 S3 上傳會觸發 Rapid 中的惡意軟體掃描：

若檔案無問題：該檔案將被儲存，系統會將包含附件及其隨附文字的訊息發送至旅宿頻道，並推送一則itinerary.conversation.attachment.success 通知。
若偵測到威脅，系統將刪除該檔案，並推送一則itinerary.conversation.attachment.failure 通知。

Conversation API 返回的對話物件範例：

{
  "itinerary_id": "987654321098",
  "expedia_confirmation_id": "1234567890",
  "property_id": "12345",
  "messages": [
    {
      "text": "Can I have an early check-in?",
      "participant": {
        "role": "traveler",
        "given_name": "John",
        "family_name": "Smith"
      },
      "creation_date_time": "2025-04-15T00:45:14.000Z",
      "message_type": "free_text",
      "delivery_status": "accepted"
    },
    {
      "text": "Please note that check-in time is 5pm and that you will need to meet with our receptionist to receive information about your room assignment.",
      "participant": {
        "role": "supplier"
      },
      "creation_date_time": "2025-04-15T00:10:12.000Z",
      "message_type": "free_text",
      "delivery_status": "accepted"
    }
  ],
  "links": {
    "add_message": {
      "method": "POST",
      "href": "/v3/conversations/1234567890/messages?token=MY5S3j36cOcL",
      "expires": "2025-04-15T00:45:14.000Z"
    },
    "add_attachment": {
      "method": "POST",
      "href": "/v3/conversations/1234567890/messages/attachments?token=MY5S3j36cOcL",
      "expires": "2025-04-15T00:45:14.000Z"
    }
  }
}

連結有效性與代幣過期

add_message和add_attachment 這兩組連結皆為臨時連結，其有效期將於「expires」欄位所指定的時間戳記，或「check-out」日期後的 30 天屆滿，以較早者為準。該對話連結本身的有效期最長為 90 天 post-stay.

在每次呼叫之前，請先評估 ``expires 欄位的值。如果已過期，或您收到 401/403 錯誤，請透過 re-run 調用「檢索預約」或「檢索對話」功能，以生成新的連結。

請聯絡您的 Expedia Group 業務代表，以啟動您的 Conversation API 整合工作。

AI-powered re-marketing 壓制與訊息主題標記

Property-initiated 被標記為「re-marketing"（推廣直接預訂或以其他方式推廣 off-platform) 的訊息）的訊息，將由 Conversation API 及旅宿訊息中心自動屏蔽。

為了讓使用者能更輕鬆且具可擴展性地使用 property-initiated 訊息，我們的對話解決方案採用了「AI-driven」模型，該模型能識別訊息中的主要主題，並將這些主題作為標籤傳送至itinerary.message.received 通知事件中。您可以使用這些標籤，來驅動您自身系統中的搜尋、路由、自動化及過濾邏輯。

旅宿訊息主題的潛在標籤

標籤	說明
入住登記指示	當旅宿分享旅客前往 check-in 或住宿期間所需的重要資訊或指示時，例如門禁密碼、櫃檯服務時間、押金資訊、身分證明文件要求等。註：「check-in」指令標籤將始終優先於「re-marketing」抑制標籤。I.e. 如果供應商發送的訊息同時包含「check-in」的詳細資訊與「re-marketing」的說明文字，旅客仍會收到該訊息。
早期 check-in / 晚期 check-out	當旅宿透過私訊分享有關早期 check-in 或後期 check-out 的額外資訊時。若提前 check-in 或延遲涉及特定費用，亦適用此情況 check-out.
餐點/飲料	如果旅宿的訊息涵蓋餐廳或酒吧的供應情況或營業時間、菜單品項或其他餐飲詳情。
維修/關閉	旅宿分享更新資訊，說明旅宿的特定區域正在維修、正在施工或因其他原因暫時關閉，可能包括游泳池、海灘、健身房或其他設施的關閉。
停車	旅宿分享有關停車選項、預訂、開放時間或每晚或每小時費用等其他說明。
寵物規定	若旅宿分享其獨特的寵物政策，或寵物入住客房/unit 所產生的相關費用。
詢問資訊/抵達時間	旅宿想詢問旅客例如住宿詳情或抵達時間等更多資訊，以便旅宿能妥善管理與規劃住宿事宜。
請求提供評論	旅宿傳送要求，希望旅客就其住宿體驗留下評論。最常寄出的 post-stay.
交通	當旅宿分享有關機場接送服務 pick-up 或 drop-off 的選項、接駁車的可用性，或行程安排說明等資訊時，
其他	若訊息中未包含前述任何標籤，系統將預設將其歸類為「其他」(行李、客房服務資訊、加床、衛生、清潔、電梯、電力、廚房／廚具、COVID-19 政策、條款與細則等)

包含主題標籤的itinerary.message.received 通知有效載荷範例：

{
  "event_id": "493ae7d4-fb3c-49fb-b180-0d7f4030aaeb",
  "event_type": "itinerary.message.received",
  "event_time": "2024-09-16T15:22:42.783857461Z",
  "itinerary_id": "9025294229844",
  "email": "test@travelnow.com",
  "message": "Please checkin before 12:00 PM!",
  "topic_tags": "Check-in",
  "affiliate_reference_id": "b086d299-2f1f-4134-a23c-f4a1c9286fac"
}

出租度假屋

啟用與度假租屋物件的直接訊息功能至關重要，因為在 Rapid API 上架的度假租屋物件中，有 84% 並未設有接待櫃檯。這些旅宿通常得靠直接傳送訊息來提供旅客以下資訊：

進入旅宿所需的個人化門禁密碼
旅宿獨有或供應之設施服務的使用說明
停車須知和指定車位

注意：旅宿訊息中心與 Vrbo 房源不相容。如果您目前正在分銷或計劃分銷 Vrbo 的房源，我們建議您整合 Conversation API。

旅宿訊息中心

一款 two-way 訊息傳遞工具，透過 pre-built 訊息介面，促進住宿業者與旅客或旅行社之間的直接互動，從而提供更流暢的 post-booking 體驗。

重要事項

「對話 API」（Conversation API）是我們全新的「API-based」對話解決方案，相較於旅宿訊息中心，它提供了更優質的使用體驗，並具備更多客製化與自動化的可能性。除非您需要 pre-built 的使用者介面體驗，否則我們建議您整合 Conversation API。

旅宿訊息中心的運作方式

旅宿訊息中心可進行設定，以啟用旅宿與旅客之間的直接訊息傳遞 (需在預訂請求中提供旅客電子郵件)，或啟用旅宿與貴公司客服專員之間的訊息傳遞 (需在預訂請求中提供客服專員電子郵件)。

旅宿訊息中心對話範例

Property-initiated 訊息旅宿希望告知旅客，他們提供往返機場的免費 round-trip 接駁車服務。

旅宿和旅客以聊天方式對話的範例。旅宿使用對話 App 來傳送和接收訊息。旅客使用電子郵件。

Traveler-initiated 訊息旅客已為其預訂申請嬰兒床服務，並希望在抵達前向旅宿再次確認此請求。

請透過 Expedia Partner Solutions 查閱旅宿訊息中心中的「旅客」及「Agent-Model」啟動要求：

>> 詳情請參閱 AWS 文件
 >> 瞭解「traveler-model」的啟動要求
 >> 了解 agent-model 的啟動需求

請聯絡您的 Expedia Group 業務代表，以啟動您的旅宿訊息中心整合。

其他資源

向旅客展示對話入口的最佳做法

以下提供一些指引，說明如何在旅客完成預訂後，向他們顯示「對話 API」連結。

在預訂確認頁面上新增「訊息飯店」或「訊息主機」按鈕
此功能可讓旅客在完成預訂後，立即向旅宿提出請求或詢問相關資訊。
在行程頁面新增「訊息飯店」或「訊息主機」按鈕
此功能可讓旅客直接從預訂頁面聯絡旅宿。
在預訂電子郵件中新增「訊息飯店」或「訊息主機」按鈕
這有助於提醒旅客，當他們收到即將到來的住宿相關更新或提醒時，可聯絡旅宿。

Conversation API 的錯誤處理

在不同的情境下可能會傳回幾種錯誤，這些錯誤均以400 編碼表示。以下列出了常見原因，以及各錯誤所伴隨的回傳訊息：

原因	訊息
輸入無效	「JSON 資料內容無效」
無法解碼或解析該代幣	「連結無效」
缺少必填的標記欄位	「連結無效」
路徑與憑證之間的確認 ID 不匹配	「連結無效」
憑證已過期 (`link.expired`)	「您點擊的連結已過期。「請再次發出 GET 對話請求以重新載入連結」
請求內容為空	「必須填寫請求內容」
訊息內容為空白或超過 20,192 個字元	「內容不得為空，且不得超過 20192 個字元」
檔案大小超過 5 MB	「檔案大小超過 5 MB 的上限。」
不支援此檔案類型	「檔案類型必須為 [application/pdf、image/jpeg、image/png] 其中之一。」
附件的對話類型不支援	「附件無效」

API 詳細資料

請在此頁面瀏覽 Conversation API 的定義，接著使用 API Explorer 或其他測試軟體，藉此了解範例與架構定義與實際輸出結果之間的對比。