Skip to content

References

Send a driver message

The driver sends a message to the traveller.

POST /v2/bookings/:bookingReference/chat-messages

Request Fields

Field Type Description Required
messageId String A time-based UUID (v1) generated by your app. Use it as the idempotency key. Random UUID (v4) is not supported. Yes
chatParticipantId String The driver identifier in your system. It must match the chat participant currently assigned to the booking. Yes
content String Plain text only. HTML and attachments are not supported. Maximum 100,000 characters. Yes
sourceLanguageCode String The language of the message content, as a 2-letter ISO 639-1 code (for example de, fr, or nl). No

Content controls

Booking.com applies content controls to every chat message. The following are removed or redacted before the message is delivered, in both directions:

  • URLs, email addresses, and phone numbers
  • Credit-card numbers and IBAN / bank details
  • HTML and script content

Send messages as plain text. Do not use chat to share links, contact details, or payment information — they will not reach the other party.

Sample Request

{
    "messageId": "671dc13e-a312-11f1-a9f7-567d4456d93b",
    "chatParticipantId": "d7-abc",
    "content": "I'm 5 minutes away, stuck in traffic.",
    "sourceLanguageCode": "en"
}

Response

HTTP 200 - OK

{
    "messageId": "671dc13e-a312-11f1-a9f7-567d4456d93b"
}

Note

If a request fails, resend it with the same messageId. The platform deduplicates messages with this ID, so a message is not delivered twice.

Message ID requirement

Message IDs must be a time-based UUID version 1. Booking.com validates the version and rejects any other version.

Warning

Only UUID v1 is accepted. Booking.com rejects a random UUID v4 and a time-ordered UUID v7 with 400 Bad Request. Make sure your library generates version 1 (time-based) values.

Library options that produce a version 1 UUID:

  • JavaScript / TypeScript: the uuid package v9+ — import { v1 as uuidv1 } from 'uuid'.
  • Java: com.fasterxml.uuid:java-uuid-generator — Generators.timeBasedGenerator().generate().
  • Python: the native uuid.uuid1().
  • Go: github.com/google/uuid v1.6+ — use uuid.NewUUID(). uuid.New() returns a v4 value and is rejected.

Retrieve the conversation history

Call this endpoint when a chat opens. It loads the thread and picks up any messages missed while your webhook was unavailable. Suppliers that do not use the webhook can poll this endpoint for conversation updates.

GET /v2/bookings/:bookingReference/chat-messages?chatParticipantId=d7-abc&limit=20

Query Parameters

Parameter Type Description Required
chatParticipantId String Must match the chat participant currently assigned to the booking. Yes
limit Integer The maximum number of messages to return. Defaults to 20. No
paginationToken String Omit it for the first request. Pass the returned token to get the next page. No

Response Fields

Field Type Description
messages Array The conversation messages, oldest first.
messages[].messageId String The message identifier. A time-based UUID (v1).
messages[].chatParticipantId String The chat participant the conversation belongs to.
messages[].senderType String Who sent the message: GUEST for the traveller, DRIVER for the driver.
messages[].content String The message text, in the sender's original language.
messages[].sentAt String When the message was sent, in UTC (ISO 8601).
paginationToken String The token for the next page. Always present; null when there are no more pages.

Sample Response

{
    "messages": [
        {
            "messageId": "671dc1e8-a312-11f1-a9f7-567d4456d93b",
            "chatParticipantId": "d7-abc",
            "senderType": "GUEST",
            "content": "I'm outside terminal 2, near the taxi rank.",
            "sentAt": "2026-04-28T13:17:41Z"
        },
        {
            "messageId": "671dc13e-a312-11f1-a9f7-567d4456d93b",
            "chatParticipantId": "d7-abc",
            "senderType": "DRIVER",
            "content": "I'm 5 minutes away.",
            "sentAt": "2026-04-28T13:18:02Z"
        }
    ],
    "paginationToken": "eyJhbGciOiJIUzI1NiJ9..."
}

Note

Messages are returned oldest first. paginationToken is always present. It is null when there are no more pages. Parse both timestamp formats: 2026-04-28T13:17:41Z and 2026-04-28T13:17:41.428Z.

Note

Treat senderType as a case-sensitive string. Match it against the documented values rather than hard-coding it.

Error responses

Status code Description
400 Bad Request A required field is missing or has an invalid format.
401 Unauthorized The token is missing or expired.
403 Forbidden The credentials do not have access to the booking or chatParticipantId.
404 Not Found The booking was not found, or the message ID does not exist in the conversation.
409 Conflict There is no active chat window. Do not show the chat UI when this is returned.
429 Too Many Requests The chat rate limit was exceeded. Back off and retry.
5xx A server error occurred. Retry with exponential backoff.

Key requirements

  • Use the same OAuth 2.0 authentication as all other Dispatch API calls.
  • Use time-based UUID v1 message IDs for driver-to-traveller messages. UUID v4 and v7 are not supported.
  • Treat message content as plain text only.
  • Parse both 2026-04-28T13:17:41Z and 2026-04-28T13:17:41.428Z timestamp formats.
  • Retry failed sends with the same messageId.
  • Recover missed messages by calling the history endpoint when the chat screen opens.
  • Use exponential backoff for retryable failures.

Further reading