# Bridge partner voice-AI

# Bridge partner voice-AI

Gli agenti vocali stile Hostie/Slang integrano **noi** — chiamano il server MCP, che espone già tutta la superficie di prenotazione che serve a un agente. Nessuna API vocale separata: gli stessi tool servono chat assistant e runtime vocali.

## Endpoint

`POST /mcp/bookings` — Laravel MCP (JSON-RPC over HTTP), autenticato con **token Sanctum bearer** (`Authorization: Bearer …`). Emetti un token con scope per locale dalle impostazioni sviluppatore; un token vede solo la propria azienda — dati di ospiti e prenotazioni non attraversano mai i tenant.

**Ability dei token**: ogni chiamata richiede l'ability mappata al suo tool — `create` per `create_booking`, `delete` per `cancel_booking`, `update` per `mark_booking_service`/`assign_table_to_booking`/`offer_waitlist_spot`, `read` per tutto il resto — e la route è rate-limited a **60 richieste/min per token**. Un token di sola `read` riceve `{"error": "forbidden"}` sui tool di scrittura.

## Tool per un agente vocale

| Tool | Uso nella chiamata |
| --- | --- |
| `list_events` | «Cosa c'è questo weekend?» — eventi e tipi in arrivo |
| `list_areas` | «Prenotate sale private?» — aree prenotabili |
| `get_event` | Dettagli di un evento prima del preventivo |
| `get_availability` | Capienza live + orari/posti aperti per un evento |
| `create_booking` | Prenota uno slot — `bookable_type` (`event`/`time`/`seat`/`area`), `bookable_id`, `number`, `from`/`to` per finestre flessibili, `name`/`email`/`phone`, `notes`, `idempotency_key` |
| `get_booking` | Rilegge una prenotazione via codice |
| `cancel_booking` | Annulla via codice — si applica la policy di cancellazione (rimborso %, cutoff) |

`list_bookings`, `list_event_types`, `list_orders`, `list_tables`, `get_order`, `get_kpi` completano la lettura quando all'agente serve reporting. Registrati anche: `list_waitlist_entries`/`offer_waitlist_spot` (letture waitlist + offerta posti), `get_guest` (scheda CRM), `list_inquiries` (lead eventi), `get_stock_levels` (giacenze), `mark_booking_service` e `assign_table_to_booking` (operazioni di sala — stato servizio e assegnazione tavoli).

## Playbook per chiamata vocale

1. Il cliente dice una data → `list_events` → scegli l'evento.
2. Numero persone/orario → `get_availability` → verifica che lo slot basti.
3. Nome/telefono → `create_booking` con `idempotency_key` per chiamata (a prova di retry — una caduta a metà prenotazione rigioca sulla stessa prenotazione, niente doppi posti).
4. Ri-leggi il codice di conferma; il cliente riceve la normale mail.
5. Annullamento: `cancel_booking` con il codice — il pricing della policy è automatico.

## Garanzie

- Hold di capienza, limiti pacchetto, controlli di stato e obbligo telefono passano da `CreateNewBooking` — identico al widget web, nessuna corsia privilegiata per la voce.
- Gli eventi a pagamento restano `pending` e si completano col normale link di checkout; l'agente deve dire al cliente di attendere la mail di pagamento.
- Gli errori tornano come `{"error": "<code>"}` — codici stabili, usabili per diramare il flusso vocale.


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