Bridge partner voice-AI
Ultimo aggiornamento: 27 ottobre 2026
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
- Il cliente dice una data →
list_events→ scegli l'evento. - Numero persone/orario →
get_availability→ verifica che lo slot basti. - Nome/telefono →
create_bookingconidempotency_keyper chiamata (a prova di retry — una caduta a metà prenotazione rigioca sulla stessa prenotazione, niente doppi posti). - Ri-leggi il codice di conferma; il cliente riceve la normale mail.
- Annullamento:
cancel_bookingcon 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
pendinge 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.