# Messaging API

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.


Version: 2.0.0

## Servers

Live
```
https://api.bookabletech.com
```

## Security

### Live

This API uses OAuth2 client credentials flow via Auth0.
**Important:** Include the `audience` parameter in your token request.
```
POST https://auth.bookabletech.com/oauth/token
{
  "grant_type": "client_credentials",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "audience": "api.bookabletech.com"
}
```


Type: oauth2

## Download OpenAPI description

[Messaging API](https://docs.bookabletech.com/_bundle/apis/production/MessagingApi.yaml)

## Messaging

Booking message operations

### Send a message for a booking

 - [POST /bookings/{bookingId}/messages](https://docs.bookabletech.com/apis/production/messagingapi/messaging/sendbookingmessage.md): 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.

### List messages for a booking

 - [GET /bookings/{bookingId}/messages](https://docs.bookabletech.com/apis/production/messagingapi/messaging/getbookingmessages.md): 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.