Skip to content
/
List messages for a booki...

Messaging API (2.0.1)

API for retrieving the operator↔partner conversation stored against a booking.

Bookable relays the conversation between the venue operator and the integration partner over email (both parties email a per-booking conversation alias and Bookable forwards each message on).

Participants can take part in two ways:

  • By email — reply to the relay email from their normal mail client (attachments supported this way only).
  • Programmatically — POST /bookings/{bookingId}/messages to send a plain-text message. Bookable stores it and relays it on to the other participant over the same conversation channel. GET returns the stored conversation stack.

The send direction is derived from the caller's role: an Integration Partner sends to the venue operator (partner_to_operator); a venue group operator sends to the integration partner (operator_to_partner). Each stored message carries this absolute direction.

Pagination: Uses page-based pagination via pageNumber and pageSize. Results are ordered by sentAt ascending (oldest first).

Availability: Real email relay is not available in the Sandbox environment. In Sandbox only the webhook-only test flow is reachable — see the direction override on SendMessageRequest, which stores the message and fires the message.received webhook to your registered sandbox callback without sending any email.

Testing your message.received receiver: prefer POST /webhooks/test (Webhook API) with eventType: message.received. It reports what each of your endpoints answered (status, body, timing, signature, payload), delivers once with a 10 second timeout, never drops a repeat, and lets you set the subject and sender. The direction override below reports none of that: a failed delivery still answers 201, and an identical message within the same hour is not delivered again.

Download OpenAPI description
MessagingApi.json
MessagingApi.yaml
Overview
URL
https://www.bookabletech.com
Bookable
hello@bookabletech.com
Languages
Servers
Live
https://api.bookabletech.com

Messaging

Booking message operations

Operations

Send a message for a booking

Request

Sends a plain-text message on the booking's operator↔partner conversation. Bookable stores the message and relays it over email to the other participant, who can reply from their normal mail client.

The delivery target is derived from the caller's role — there is no recipient field:

  • Integration Partner — delivered to the venue operator (direction: partner_to_operator).
  • Venue group operator — delivered to the integration partner (direction: operator_to_partner).

Attachments cannot be sent via this endpoint; add them by replying to the relay email instead.

Security
Live(Required scopes:
venue-booking:messaging:write
)
Path
bookingIdstringrequired

The composite booking ID (e.g. 29|CO|6a3e866a4989b3b73d78f011|B)

Example: 29|CO|6a3e866a4989b3b73d78f011|B
Headers
X-Correlation-IDstring

An optional ID which you can use to track transactions across multiple systems. It can have any value, but we recommend avoiding . characters. Mirrored back in a response header.

Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
X-Partner-Referencestring

Required for Bookable Agents. Identifies the partner for whom the request is being made. This header must be provided when making requests with the agent:write scope.

Accepts either form:

  • a partner reference, e.g. thefork.com
  • a partner id, e.g. 288 — the same id returned by GET /agent/impersonation-targets

A value matching a known partner reference always resolves as that reference; it is only treated as a partner id when it does not. Most partners have no reference configured, so the partner id is generally the form to use — the one exception being a reference spelled as digits, which still takes precedence over the partner whose id is that number.

Bodyapplication/jsonrequired
bodystring[ 1 .. 5000 ] charactersrequired

Plain-text message body. Delivered to the other conversation participant.

Example: "Could you please accommodate a high chair for us?"
directionstring or null

Sandbox-only test override. Forces the absolute message direction so a partner can trigger their own message.received webhook (send operator_to_partner) against their registered sandbox callback — without a real operator or an inbound email round-trip. Ignored outside the Sandbox environment, where the direction is derived from the caller's role. When set in Sandbox the email relay is skipped (webhook-only): the message is stored and the webhook fires, but no email is sent. To test your receiver rather than store a message, use POST /webhooks/test instead (see the API description).

Enum"operator_to_partner""partner_to_operator"
Example: "operator_to_partner"
curl -i -X POST \
  'https://api.bookabletech.com/bookings/29|CO|6a3e866a4989b3b73d78f011|B/messages' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Correlation-ID: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA' \
  -H 'X-Partner-Reference: string' \
  -d '{
    "body": "Could you please accommodate a high chair for us?",
    "direction": "operator_to_partner"
  }'

Responses

Message stored and relayed to the other participant

Bodyapplication/json
idstringrequired

Unique message identifier

Example: "msg_abc123"
subjectstring or null

Email subject line

Example: "Table for Jane Smith"
bodystringrequired

Message body text

Example: "Could you please accommodate a high chair for us?"
senderEmailstring or null

Email address of the sender

Example: "partner@example.com"
senderNamestring or null

Display name of the sender

Example: "Jane Smith"
directionstringrequired

Absolute message direction: operator_to_partner = the venue operator sent it; partner_to_operator = the integration partner sent it.

Enum"operator_to_partner""partner_to_operator"
Example: "partner_to_operator"
attachmentsArray of objects or null(MessageAttachment)

Attachment metadata (bytes are exchanged over email, not via this API).

sentAtstring(date-time)required

ISO 8601 timestamp when the message was sent

Response
application/json
{
  "id": "msg_ghi789",
  "subject": "ABR-1042 Message regarding your booking",
  "body": "Could you please accommodate a high chair for us?",
  "senderEmail": "partner@example.com",
  "senderName": "Jane Smith",
  "direction": "partner_to_operator",
  "sentAt": "2026-06-01T10:00:00Z"
}

List messages for a booking

Request

Returns all stored messages for the given booking's operator↔partner conversation, ordered by sentAt ascending (oldest first). Each message's direction states who sent it and who received it.

Access is scoped to the caller's venue group: Integration Partners see only messages for bookings belonging to their associated venues.

Security
Live(Required scopes:
venue-booking:messaging:read
)
Path
bookingIdstringrequired

The composite booking ID (e.g. 29|CO|6a3e866a4989b3b73d78f011|B)

Example: 29|CO|6a3e866a4989b3b73d78f011|B
Query
pageNumberinteger>= 1

Page number (default 1).

Default 1
pageSizeinteger[ 1 .. 100 ]

Items per page (default 20, max 100).

Default 20
Headers
X-Correlation-IDstring

An optional ID which you can use to track transactions across multiple systems. It can have any value, but we recommend avoiding . characters. Mirrored back in a response header.

Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
X-Partner-Referencestring

Required for Bookable Agents. Identifies the partner for whom the request is being made. This header must be provided when making requests with the agent:write scope.

Accepts either form:

  • a partner reference, e.g. thefork.com
  • a partner id, e.g. 288 — the same id returned by GET /agent/impersonation-targets

A value matching a known partner reference always resolves as that reference; it is only treated as a partner id when it does not. Most partners have no reference configured, so the partner id is generally the form to use — the one exception being a reference spelled as digits, which still takes precedence over the partner whose id is that number.

curl -i -X GET \
  'https://api.bookabletech.com/bookings/29|CO|6a3e866a4989b3b73d78f011|B/messages?pageNumber=1&pageSize=20' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'X-Correlation-ID: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA' \
  -H 'X-Partner-Reference: string'

Responses

Message list retrieved successfully

Bodyapplication/json
metaobject
dataArray of objects(Message)required

Messages for the current page, ordered by sentAt ascending.

data[].​idstringrequired

Unique message identifier

Example: "msg_abc123"
data[].​subjectstring or null

Email subject line

Example: "Table for Jane Smith"
data[].​bodystringrequired

Message body text

Example: "Could you please accommodate a high chair for us?"
data[].​senderEmailstring or null

Email address of the sender

Example: "partner@example.com"
data[].​senderNamestring or null

Display name of the sender

Example: "Jane Smith"
data[].​directionstringrequired

Absolute message direction: operator_to_partner = the venue operator sent it; partner_to_operator = the integration partner sent it.

Enum"operator_to_partner""partner_to_operator"
Example: "partner_to_operator"
data[].​attachmentsArray of objects or null(MessageAttachment)

Attachment metadata (bytes are exchanged over email, not via this API).

data[].​sentAtstring(date-time)required

ISO 8601 timestamp when the message was sent

Response
application/json
{
  "meta": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 2,
    "totalPages": 1
  },
  "data": [
    { … },
    { … }
  ]
}