Skip to content

Understanding the Chat Webhook

What does it do?

The chat webhook lets Booking.com forward traveller messages to your driver app for Rides bookings. When a traveller sends a message, Booking.com sends an HTTP POST request to the webhook endpoint that your organisation registered. Your driver app shows the message in the conversation thread. The driver then replies through the Dispatch API.

The chat integration lets you:

  • Receive traveller messages through a webhook.
  • Send driver messages to travellers.
  • Load the conversation history, including any messages missed while your webhook was unavailable.

Why use it?

If your driver app supports in-app messaging, the chat webhook gives travellers and drivers a real-time way to communicate during a Rides booking. Chat lets drivers receive operational messages from travellers — for example, pickup-location updates or arrival instructions — without a separate communication channel.

Note

Booking.com delivers chat events only for bookings where the driver assignment set chatEnabled: true.

How does it work?

  1. Self-enrol for the CHAT webhook. Add CHAT to your POST /v1/webhooks request.
  2. Implement the receiver route POST /v2/bookings/:bookingReference/chat-messages on your server. Return a 2xx response within 30 seconds. No response body is required.
  3. Declare chat support during driver assignment. Add chatEnabled: true and a chatParticipantId to your existing Assign a driver request.

Your API must be served via HTTPS with a valid SSL certificate and secured using OAuth 2.0 authentication.

The inbound webhook uses the same resource path as the outbound send-message endpoint. Only the host differs:

  • Traveller to driver (inbound): Booking.com posts to your server.
  • Driver to traveller (outbound): Your server posts to Booking.com.

Implement your receiver as a single parameterised route, for example app.post('/v2/bookings/:bookingReference/chat-messages', handler).

Key requirements

  • Serve your API over HTTPS with a valid SSL certificate.
  • Register CHAT together with the webhook event types you already use.
  • Set chatEnabled: true during driver assignment to enable chat delivery for a booking.
  • Provide chatParticipantId when chat is enabled. It must match the participant currently assigned to the booking.
  • Return a 2xx response to inbound webhook requests within 30 seconds.
  • Deduplicate inbound messages with messageId.
  • Recover missed messages with the conversation history endpoint when the chat screen opens.

Further reading