Messaging API - Best Practices

Conventions

Base URL and content type

Documented enum values in this contract (response enums are extensible):

message_type on send is not a request field (the body is {"message":{"content":"..."}} with optional attachment_ids). On GET and webhook, ordinary text messages appear as free_text. Other stored types are returned as-is (special_request, agoda_auto_response, scheduled_message, auto_reply, notification, cancellation_waiver, cancellation_reminder, no_show_confirmation, host_email, engage_email, and similar). Do not drop non-free_text values.

No request field in v1 is an enum. If a later compatible revision adds a request enum, only the documented values are accepted.

The Message object has no status field, no read_by field, and no reply_to field. v1 has no threading. Delivery is not a partner-visible processing enum. Acceptance is the 202. This API does not expose per-message read receipts; the read signal is the participant unread counter.

Envelope

Every JSON response body contains all four fields: data, errors, warnings, and meta.

On success, errors is [] and warnings is []. On error, data is null, errors is a non-empty array, warnings is [], and meta is present.

Exceptions: PUT .../read returns 204 No Content with no body. Download success returns the file bytes with no JSON envelope. Those are the only success responses without the envelope.

meta contains ruid, an opaque string for support correlation. The X-Request-Id response header is present on every response, including 204 No Content, and equals meta.ruid whenever a JSON body is present.

Success (every JSON success body includes data.ok):

{
  "data": {
    "ok": true
  },
  "errors": [],
  "warnings": [],
  "meta": {
    "ruid": "dd28b426-70c2-4b16-8f16-0edddac1ac2f"
  }
}

Error:

{
  "data": null,
  "errors": [
    {
      "code": "INVALID_REQUEST",
      "message": "The request is invalid.",
      "field": "message.content"
    }
  ],
  "warnings": [],
  "meta": {
    "ruid": "dd28b426-70c2-4b16-8f16-0edddac1ac2f"
  }
}

Identifiers

All public identifiers are strings. Treat them as opaque. Do not convert them to JavaScript numbers or another narrower numeric type.

Clients MUST NOT construct identifiers or infer ownership from their values. Use only values returned by this API or already issued to your integration for the entitled property (Agoda property ID and Agoda booking ID).

Timestamps and ordering

• Timestamps use RFC 3339 UTC with a Z suffix and millisecond precision, for example 2026-07-23T07:15:30.123Z.
• Conversation lists are ordered by latest externally visible activity first, then conversation_id as a deterministic tie-breaker.
• Messages are ordered by message_id descending, most recent first. message_id, not timestamp, is the paging and ordering authority.

Pagination

List and conversation-detail pages contain at most 50 items. Agoda may return fewer items. Keep requesting the next page until next_page_id is null. A page with fewer than 50 items is not necessarily the last page. Do not send limit, page_size, offset, or cursor.

The reservation-conversation endpoint returns the newest at most 50 eligible messages and does not paginate. data.next_page_id is present and always null on that endpoint. Passing page_id to that endpoint returns 400 INVALID_PAGE_ID. To read messages older than the returned page, use the conversation_id from that response with Get conversation detail.

Unexpected query parameters are rejected with 400 INVALID_REQUEST. This is deliberate: a client sending an undocumented pagination parameter fails immediately and visibly, rather than silently re-reading page one.

Paginated success responses put the continuation token in data.next_page_id, as a sibling of data.conversations (list) or data.conversation (reservation and detail). data.next_page_id is always present. On list and conversation-detail, it is a string when a later page is currently known, and null on the last page. On the reservation-conversation endpoint, it is always null. Pass a non-null data.next_page_id back as the page_id query parameter to fetch the next page of a paginated endpoint. Send 202 success bodies do not include next_page_id.

{
  "data": {
    "ok": true,
    "conversations": [],
    "next_page_id": "eyJvIjoiYyIsInAiOiI0MTgwOTIzNDUifQ"
  },
  "errors": [],
  "warnings": [],
  "meta": {
    "ruid": "dd28b426-70c2-4b16-8f16-0edddac1ac2f"
  }
}

A page_id is opaque and bound to the authenticated integration, property, filters, ordering version, and last position. Reusing it with different parameters returns 400 INVALID_PAGE_ID. Pages are mutable: deduplicate conversation rows by conversation_id and refresh from the first page when you need a current view. Deduplicate messages by message_id.

This API does not impose a three-month retrieval window. Message history for an eligible conversation is not truncated by age in v1.

Send attempts

Every POST that sends a message is a new send attempt.

Do not send Idempotency-Key, a client message ID, a request fingerprint, or a replay key. Those headers and fields are not part of this API. Repeating a POST creates another send attempt and can create another guest-visible message.

A send timeout, connection loss, or 500/503 after a POST has an unknown acceptance outcome. Do not blindly repeat the same body.

See Best practices and retry guidance.

Conversation access and write window

Partners MUST treat access as the send and upload eligibility signal and recheck it on every send POST and every upload POST. Agoda rechecks send and upload eligibility for every write POST. A previous read_write response does not guarantee that a later write will be accepted. A conversation that is not writable returns 403 CONVERSATION_READ_ONLY for send and upload.

Agoda messaging lifetime:

• The usual default is that the property may send until checkout + 14 days. That default is not the only expiry. A conversation can have a stored expiration that is not 14 days after checkout; when that stored expiration is present, it is the write-window authority. Recheck access; do not assume a hard 14-day rule.
• A guest message extends the writable window to max(current expiration, that guest message's created timestamp + 7 days). A guest message inside the base window can have no effect. Example: a guest message on day 3 after checkout extends to day 10, which is earlier than checkout + 14, so the base window still wins. Property messages never extend the window.
• After the writable window, property send and upload are not eligible while the conversation may remain readable (read_only). Reads (list, detail, download, metadata, mark-read) may continue.
• Cancellation does not move the clock. The window is computed from checkout, not from a cancellation date.
• Guests are not capped at a fixed number of days after checkout.

Do not treat the window as "checkout + 21 days". Rely on access.

The Conversation object has no status field. Writability is access only.

Resource models

All resources below are JSON objects. Required response fields are non-null unless explicitly stated as nullable. The field sets below are closed: a conforming response includes exactly these fields for each object (unknown additive keys on a later compatible revision must be ignored).

Participant

{
  "type": "property",
  "unread_messages_count": 1
}

A conversation returns exactly one property projection, exactly one guest projection, and at most one agoda projection. Include agoda when Agoda is a participant on the thread. At most three unique participants: at most one of each. No participant ID, email address, name, or delivery address is exposed.

unread_messages_count is a counter Agoda maintains for each participant on the conversation. It increases when a message arrives that the participant has not seen, and it is reset to zero both by the mark-read call and when that participant themselves sends a message. It is not a live count of unread messages within the page you were returned, and it may legitimately differ from the messages visible in the response.

This API does not expose per-message read receipts. The participant unread counter is the read signal.

Participants expose type and unread_messages_count only.

Message

The Message object has exactly these seven fields: message_id, message_type, content, timestamp, sender_type, attributes, attachment_ids. There is no status field, no read_by field, and no reply_to field.

{
  "message_id": "918273644",
  "message_type": "free_text",
  "content": "Can we check in early?",
  "timestamp": "2026-07-23T07:15:30.123Z",
  "sender_type": "guest",
  "attributes": {},
  "attachment_ids": []
}

Messages in a page are ordered by message_id descending, most recent first.

Conversation

The Conversation object has no status field.

{
  "conversation_id": "418092345",
  "conversation_reference": "9384756102",
  "conversation_type": "reservation",
  "access": "read_write",
  "participants": [
    { "type": "property", "unread_messages_count": 1 },
    { "type": "guest", "unread_messages_count": 0 },
    { "type": "agoda", "unread_messages_count": 0 }
  ],
  "messages": [
    {
      "message_id": "918273644",
      "message_type": "free_text",
      "content": "Can we check in early?",
      "timestamp": "2026-07-23T07:15:30.123Z",
      "sender_type": "guest",
      "attributes": {},
      "attachment_ids": []
    }
  ]
}

A newly created or existing empty conversation has "messages": []. Property listings may include empty conversations; those rows still return "messages": [].

On the list endpoint, the conversation objects live in data.conversations. On the reservation and detail endpoints, the conversation object lives in data.conversation. data.next_page_id is a sibling of that array or object, not a field inside the conversation. It is always present on those three success bodies. On list and conversation-detail it is a string, or null on the last page. On the reservation-conversation endpoint it is always null.

Message size

Agoda rejects a send with 413 MESSAGE_TOO_LARGE unless both of the following hold:

1. content.length is at most 2800 UTF-16 code units.
2. The modified-UTF-8 encoded size of content is at most 2984 bytes.

Both rules are normative. The 2800 code-unit limit is not sufficient on its own. 2,800 Thai characters are about 8,400 modified-UTF-8 bytes and are rejected by the byte rule.

Modified UTF-8 (the encoding used for the byte rule):

• BMP characters encode in 1 to 3 bytes.
• U+0000 encodes in 2 bytes.
• Supplementary-plane characters (most emoji) encode in 6 bytes because they are stored as UTF-16 surrogate pairs.

Malformed UTF-16 (for example an unpaired surrogate) is 400 INVALID_REQUEST, not 413. 413 is used for the size dual rule and for an uploaded file larger than 10 MiB.

Empty content is 400 INVALID_REQUEST. Unknown fields on the send body are 400 INVALID_REQUEST. Unsupported media type, a missing upload file, or an image that contains a QR code is 400 INVALID_REQUEST.

Agoda does not accept and truncate oversized content. Reduce or split the text and retry only after you confirm a send is still needed.

Best practices and retry guidance

Treat conversation access as the write-eligibility signal on every send POST and every upload POST. Recheck it on every write. A previous read_write does not guarantee a later write. See Conversation access and write window.

Every POST is a new send attempt. Do not send Idempotency-Key, a client message ID, a request fingerprint, or a replay key.

Privacy and security

• Use the existing Supply Connectivity credential controls for every API request.
• Use HTTPS and validate TLS certificates for API and webhook traffic.
• Do not cache conversation or list data. Respect Cache-Control: no-store.
• Treat guest message content and the documented identifiers as partner data. Protect them according to your applicable privacy, security, and retention obligations.
• Do not expect private participant contact data, credentials, or dependency data in this API. Do not expect file bytes on the webhook; use download for bytes. attachment_ids may appear on Message and webhook payloads.
• For webhook receivers, restrict the endpoint to the required public HTTPS shape, validate the payload, and maintain durable deduplication. Agoda authenticates callback POSTs with OAuth 2.0 client credentials (Authorization: Bearer). Treat the notification as a hint and confirm with a conversation-detail GET before acting. See Webhook contract.

Support correlation

For integration support, provide enough information to identify the request without sending credentials or unnecessary guest content:

• meta.ruid or X-Request-Id
• UTC timestamp of the request or webhook delivery
• property_id
• conversation_id, when available
• conversation_reference, when relevant
• HTTP status and error code
• For webhook issues, metadata.uuid and your receiver's HTTP response status

Contact Agoda Connectivity with those fields. Do not send credentials or full guest message content unless Connectivity asks for a specific excerpt.