Skip to content

Getting started with Chat

Booking.com offers in-app messaging between drivers and travellers for Rides bookings. Travellers and drivers communicate in the app, so they do not need to exchange personal phone numbers. Chat is an extension of your existing Taxi Supplier API integration. You do not need a separate chat platform or a new authentication model.

What you build

  • A webhook endpoint on your server to receive traveller messages.
  • A conversation view in your driver app to show the thread and to send messages.
  • Logic to enable chat for a booking when you assign the driver.

What Booking.com provides

  • A webhook that forwards traveller messages to your server.
  • REST endpoints to send driver messages and to load the conversation history.

Authentication

Chat uses your existing authentication. Use the same OAuth 2.0 authentication as all other Dispatch API calls. No new credentials are required.

API changes summary

Endpoint Change Summary
POST /v2/bookings/:bookingReference/assignDriver Modified New optional chatEnabled and chatParticipantId request fields.
POST /v2/bookings/:bookingReference/chat-messages New The driver sends a message to the traveller.
GET /v2/bookings/:bookingReference/chat-messages New Retrieve the conversation history.

How to get started

  1. Register for the CHAT webhook event, together with the events you already use. See Self-enrolment.
  2. Implement the webhook receiver to get traveller messages. See Understanding the chat webhook.
  3. Declare chat support on driver assignment. Add chatEnabled: true and a chatParticipantId to your Assign a driver request.
  4. Connect your driver app to the chat endpoints to load the history and to send driver replies.

Key requirements

  • Chat is opt-in per driver assignment. Do not set chatEnabled: true unless the assigned driver's app supports chat.
  • chatParticipantId must identify the participant currently assigned to the booking.
  • Use the conversation history endpoint when a chat opens, to load the thread and to pick up any messages missed while your webhook was unavailable. Suppliers that do not use the webhook can poll this endpoint for updates.
  • The existing Assign Driver requirements still apply: the required booking state, stateHash, and driver or vehicle details.

Further reading