# Voice-AI partner bridge

# Voice-AI partner bridge

Hostie/Slang-style voice agents integrate **us** — they call the MCP server, which already exposes the full booking surface an agent needs. No separate voice API to maintain: the same tools serve chat assistants and voice runtimes.

## Endpoint

`POST /mcp/bookings` — Laravel MCP (JSON-RPC over HTTP), authenticated with a **Sanctum bearer token** (`Authorization: Bearer …`). Issue a scoped token per venue from the developer settings; a token only ever sees its own company — guest and booking data never crosses tenants.

**Token abilities**: each call needs the ability mapped to its tool — `create` for `create_booking`, `delete` for `cancel_booking`, `update` for `mark_booking_service`/`assign_table_to_booking`/`offer_waitlist_spot`, `read` for everything else — and the route is rate-limited to **60 requests/min per token**. A `read`-only token gets `{"error": "forbidden"}` on write tools.

## Tools a voice agent needs

| Tool | Use on a call |
| --- | --- |
| `list_events` | "What's on this weekend?" — upcoming events + types |
| `list_areas` | "Do you take private-room bookings?" — bookable areas |
| `get_event` | Details for one event before quoting |
| `get_availability` | Live capacity + open times/seats for an event |
| `create_booking` | Book a slot — `bookable_type` (`event`/`time`/`seat`/`area`), `bookable_id`, `number`, `from`/`to` for flexible windows, `name`/`email`/`phone`, `notes`, `idempotency_key` |
| `get_booking` | Read back a booking by code |
| `cancel_booking` | Cancel by code — cancellation policy applies (refund %, cutoff) |

`list_bookings`, `list_event_types`, `list_orders`, `list_tables`, `get_order`, `get_kpi` round out read-side reporting when the agent needs it. Also registered: `list_waitlist_entries`/`offer_waitlist_spot` (waitlist reads + spot offers), `get_guest` (CRM card), `list_inquiries` (event leads), `get_stock_levels` (inventory), `mark_booking_service` and `assign_table_to_booking` (floor ops — service state and seating).

## Voice-call playbook

1. Caller says a date → `list_events` → pick an event.
2. Party size/time → `get_availability` → confirm the slot fits.
3. Name/phone → `create_booking` with a per-call `idempotency_key` (retry-safe — a dropped call mid-book replays to the same booking instead of double-seating).
4. Read the confirmation code back; the booker gets the normal confirmation mail.
5. Cancel later: `cancel_booking` with the code — policy pricing is automatic.

## Guarantees

- Capacity holds, package limits, state checks and phone requirements run through `CreateNewBooking` — identical to the web widget, no voice bypass lane.
- Paid events land `pending` and complete via the normal checkout link; the agent should tell the caller to watch for the payment email.
- Errors come back as `{"error": "<code>"}` — codes are stable, safe to branch on in the voice flow.


---
> Source: https://placeful-app.com/en/docs/developer/voice-ai