Bookings & payments
When the assistant offers a booking, the user taps Confirm on its card. From SDK 2.2.0 you choose who completes it: Voqal, through your backend, or your own app, with its own booking API. Both modes are opt-in. Leave the settings alone and 2.2.0 behaves exactly like 2.1.0.
Who books it
| Mode | bookingMode | What happens |
|---|---|---|
| Voqal books it | server | The default. Voqal calls your backend's booking tool once the user confirms. You write nothing, or optionally an Add-funds callback for a short wallet. |
| Your app books it | host | Voqal hands the confirmed booking to your app, which books it with its own API and returns the outcome. A booking handler is required. |
The mode is a setup-time setting, bookingMode. Only confirm cards that carry booking details are handed to your app. Every other confirm card, such as a payment link, still runs through Voqal in both modes.
What your app receives
A booking confirm card carries a details object next to the rows the user reads. The SDK decodes it into VoqalBookingDetails: the venue, the court or resource, the date and times, the duration, the price, deposit and currency, and confirmId. Every field is optional, and the full object is also kept as-is (dictionary on iOS, fields on Android and Flutter), including any ids your backend needs.
{ "type": "confirm", "title": "Create booking", "rows": [ [ "Venue", "Riverside Club" ] ], "details": { "action": "create_booking", "venue": "Riverside Club", "court": "Court B", "date": "2026-11-17", "start": "21:00", "end": "22:00", "duration_minutes": 60, "price": null, "deposit": 30, "currency": "USD", "confirm_id": "3f0c9a52-6d1e-4b7a-9c35-8e2f1a7d4b60" }}- Times are venue-local wall-clock.
dateisyyyy-MM-dd;startandendareHH:mm. Don’t convert them from the phone’s time zone. - Price, deposit and currency can be nullwhen your backend didn’t return them.
Voqal books it
This is the default and needs no code. When the user confirms, Voqal calls your backend’s booking tool and shows the result. If your backend turns the booking down because the user’s wallet is short, the assistant shows an Add-funds card instead of an error. It states the amount due and has one button that hands the user back to your app.
The Add-funds card
addFundsButtonTitlesets the button’s label, in English and Arabic. The SDK shows the one that matches the conversation. The default is “Add funds”.- Tapping the button calls your Add-funds callback with the shortfall’s
amountandcurrency. Either can be null when it isn’t known. Open your wallet or top-up screen there. - With
dismissOnAddFunds(the default), the assistant closes first and the callback fires after, so the screen you open stays in front. - Set the callback whenever a booking can go through Voqal. Without it, the button closes the assistant and nothing else happens.
extension AppVoqalDelegate: VoqalAddFundsHandler { func voqalDidTapAddFunds(amount: Double?, currency: String?) { // With dismissOnAddFunds the assistant has already closed. router.openWallet(prefill: amount, currency: currency) }}Your app books it
Set bookingModeto host and implement the booking handler. When the user taps Confirm, the SDK calls your handler with the booking’s details and waits. You book it with your own API and return a VoqalBookingResult. The SDK reports that result to Voqal, and the assistant carries on with it in context (“You’re booked, reference 8812”).
iOS
Adopt VoqalBookingHandler and VoqalAddFundsHandler on the delegate you already pass to the SDK. VocalButtonDelegate itself is unchanged from 2.1.0. Both callbacks run on the main actor.
configuration.bookingMode = .host // default .server: Voqal books itconfiguration.addFundsButtonTitle = VoqalLocalizedText(en: "Top up wallet", ar: "اشحن المحفظة")configuration.dismissOnAddFunds = true // close the assistant firstconfiguration.hostActionTimeoutSeconds = 300 // then report unknownextension AppVoqalDelegate: VoqalBookingHandler { @MainActor func voqalDidConfirmBooking(_ details: VoqalBookingDetails) async throws -> VoqalBookingResult { let response = try await bookingsAPI.create( idempotencyKey: details.confirmId, // one card never books twice date: details.date, // "2026-11-17", venue-local start: details.start, // "21:00" end: details.end, fields: details.dictionary // every field the card carried ) guard response.isBooked else { return VoqalBookingResult(status: .failed, message: response.message, code: response.errorCode) } return VoqalBookingResult(status: .success, message: "Booked. Ref \(response.reference)", reference: response.reference) }}Android
onBookingConfirmed and onAddFundsTapped are new optional members of VoqalDelegate. The booking callback is a suspend function that runs on the main thread.
VoqalConfiguration( requestId = "prod-yourapp", apiKey = "pk_live_…", bookingMode = VoqalBookingMode.HOST, // default SERVER: Voqal books it addFundsButtonTitle = VoqalLocalizedText( english = "Top up wallet", arabic = "اشحن المحفظة", ), dismissOnAddFunds = true, hostActionTimeoutSeconds = 300,)class VoqalCredentials( private val authStore: AuthStore, private val bookings: BookingsApi,) : VoqalDelegate { override fun getToken(): String = authStore.currentToken // Called on the main thread; switch dispatchers for network work. override suspend fun onBookingConfirmed( details: VoqalBookingDetails, ): VoqalBookingResult = withContext(Dispatchers.IO) { val response = bookings.create( idempotencyKey = details.confirmId, // one card never books twice date = details.date, start = details.start, end = details.end, fields = details.fields, ) if (response.isBooked) { VoqalBookingResult( VoqalBookingStatus.SUCCESS, message = "Booked. Ref ${response.reference}", reference = response.reference, ) } else { VoqalBookingResult( VoqalBookingStatus.FAILED, message = response.message, code = response.errorCode, ) } } // The assistant has already closed. Don't capture an Activity here. override fun onAddFundsTapped(amount: Double?, currency: String?) { navigator.openWallet(amount, currency) } override fun onError(error: Throwable) { if (error is VoqalOutcomeReportError) { bookings.reconcile(error.confirmId, error.outcomeStatus) } }}Flutter
The plugin exposes the same three callbacks on Voqal. They are process-global, so clear them in dispose() if they capture widget state.
await voqal.setup(const VoqalConfig( apiKey: 'pk_live_…', bookingMode: VoqalBookingMode.host, // default .server: Voqal books it addFundsButtonTitle: VoqalLocalizedText(en: 'Top up wallet', ar: 'اشحن المحفظة'), dismissOnAddFunds: true, hostActionTimeoutSeconds: 300,));voqal.onBookingConfirmed = (VoqalBookingDetails booking) async { final response = await bookingsApi.create( idempotencyKey: booking.confirmId, // one card never books twice date: booking.date, start: booking.start, end: booking.end, fields: booking.fields, ); if (response.isBooked) { return VoqalBookingResult(status: VoqalBookingStatus.success, message: 'Booked. Ref ${response.reference}', reference: response.reference); } return VoqalBookingResult(status: VoqalBookingStatus.failed, message: response.message, code: response.errorCode);};// The assistant has already closed, so push from your own navigator.voqal.onAddFundsTapped = (double? amount, String? currency) { navigatorKey.currentState?.pushNamed('/wallet', arguments: amount);};voqal.onError = (VoqalError e) { if (e.type == VoqalErrorType.outcomeReport) { bookingsApi.reconcile(confirmId: e.confirmId, reported: e.outcomeStatus); }};The confirm id
Every booking card carries its own confirmId, a unique id that can be used once. Pass it to your booking API as the idempotency key. Then a repeated call for the same card, say after a timeout or a retry, can never book twice. Voqal sends the same id back with the outcome, so a result is always tied to the card the user confirmed. A card can be settled once, and only within two hours of being shown.
Outcomes, failures & timeouts
Whatever your handler does, the user gets an answer. Here is what each case reports and what the user sees:
| Your handler | Reported as | What the user sees |
|---|---|---|
| Returns success | success | A confirmation, with your message and reference. |
| Returns failed | failed, with your code | Your message, shown as written (trimmed, up to 300 characters). |
| Throws | failed, host_error | That the booking didn't go through. |
| Is missing or returns nothing | failed, host_no_result | That the booking didn't go through. |
| Times out | unknown, host_timeout | That the booking couldn't be confirmed, and to check their bookings. |
- A timeout is unknown, not failed. Your booking may still be going through, so the assistant never claims either way. It asks the user to check their bookings. The default wait is 300 seconds, because the user may be topping up meanwhile. Values are clamped between 1 second and 1 hour.
- Expect to be abandoned.After the timeout the SDK stops waiting. On iOS and Android it cancels your task, so stop work when it’s cancelled. A Dart future can’t be cancelled, so a Flutter handler keeps running. Either way a late result is logged and never shown, so don’t open UI from it.
- Write the message for the user. On failure your message is shown as it is, so write it in plain language. English or Arabic both work; send whichever your backend has.
Reconciling a lost report
Your app can make the booking and Voqal can still fail to record it, for example when the network drops. The booking stands, but the assistant doesn’t know about it. The SDK tells you through its error callback with a VoqalOutcomeReportError carrying the outcome you reported, a reason code and the confirmId. Look up your own booking by that id.
| Platform | Where it arrives |
|---|---|
| iOS | voqalButton(didFailWith:) |
| Android | VoqalDelegate.onError |
| Flutter | Voqal.onError, type VoqalErrorType.outcomeReport |
Errors carry codes, ids and type names only, never user data.
Turning it on
Two pieces are set up on your assistant, not in the SDK. Tell us before you ship and we turn them on:
- Host mode.Until it’s on for your assistant, Voqal rejects the outcome your app reports. The user would see an error even though your app made the booking.
- The Add-funds card. Tell us which error codes your backend returns for a short wallet, so those show the card rather than a failure.
Email uswith your publishable key and we’ll set it up.
Reference
| Setting | Default | Description |
|---|---|---|
bookingMode | server | Who completes a confirmed booking: Voqal (server) or your app (host). |
addFundsButtonTitle | “Add funds” | The Add-funds button's label, in English and Arabic. |
dismissOnAddFunds | true | Close the assistant before the Add-funds callback fires. |
hostActionTimeoutSeconds | 300 | How long to wait for your handler before reporting unknown. |
| Platform | Callbacks |
|---|---|
| iOS | voqalDidConfirmBooking(_:) from VoqalBookingHandler, and voqalDidTapAddFunds from VoqalAddFundsHandler. Adopt both on your delegate. |
| Android | onBookingConfirmed and onAddFundsTapped on VoqalDelegate |
| Flutter | Voqal.onBookingConfirmed and Voqal.onAddFundsTapped |
Setting names are the same on every platform. Android uses upper-case enum values, such as VoqalBookingMode.HOST. See Configuration for every other setting.
