Messaging API - Introduction

Partner-facing contract for the Channel Manager Messaging API.

This document is the only definition of the partner-visible wire: paths, HTTP statuses, JSON fields, enums, and examples. Channel Manager engineers should implement against this contract.

Governing principle. This contract is Agoda's. Where Agoda's messaging platform has a hard stop or an established behaviour, that behaviour is the contract. Do not assume another OTA's calendar, identifiers, or field names apply.

Base URL: https://supply.agoda.com/api/v1/messaging

Authenticate with the existing Supply Connectivity authentication method assigned to your integration.

Introduction and capabilities

This guide is for Channel Manager engineers integrating guest-property messaging for Agoda-connected hotels.

The API provides eight REST operations on reservation conversations: listing conversations, reading a conversation by booking ID or conversation ID, sending a text message when the conversation is writable, marking a conversation read for the property role, uploading an attachment, downloading an attachment, and reading attachment metadata. Send may include attachment_ids and still requires non-empty text. A webhook notifies the Channel Manager when a new eligible message is available.

Reservation threads include property and guest, and may include Agoda (agoda). Messages from agoda are eligible like any other.

Capabilities

Capability	Status	Notes
List property conversations	Supported	Eligible reservation conversations for an entitled Agoda property, including empty conversations. Each row includes the latest eligible message, or `messages: []` when empty.
Get reservation conversation	Supported	Reads a reservation conversation by Agoda booking ID. If none exists, the request may create and return one empty reservation conversation. Ambiguous matches return a conflict. Returns the newest at most 50 eligible messages; does not paginate.
Get conversation detail	Supported	Eligible messages in descending `message_id` order, with pagination. Use this to read messages older than the page returned by the reservation conversation endpoint.
Send free-text message	Supported	Accepts a text send only when the conversation is currently `read_write`. `content` is required and non-empty. `attachment_ids` is optional (omit or `[]`). Acceptance means accepted for processing, not that the message is already visible on a later read.
Mark conversation read	Supported	Sets the property's unread counter for that conversation to zero.
Upload attachment	Supported	JPEG and PNG, maximum 10 MiB. Wait for metadata before download. Files are kept for 28 days.
Download attachment	Supported	File bytes, not JSON. Wait for metadata before download. Files are kept for 28 days.
Get attachment metadata	Supported	`file_name`, `file_type`, and `file_size` only. Wait for metadata before download. Files are kept for 28 days.
Webhook new-message notification	Supported	Agoda configures the HTTPS destination during certification. Delivery is at-least-once. Payload may include `attachment_ids` (ids only, not file bytes).