Authenticated API

Voice AI endpoints require a valid JWT Bearer token with staff roles. Accessible via the API gateway at /v1/voice-ai/* and /v1/speech/*.

Drive-Thru

Lane-aware voice sessions with speed of service tracking for drive-thru operations.

Base Path: /api/v1/voice/drive-thru

---

Drive-Thru Session Phases

Phase	Code	Description
Greeting	greeting	Customer arrived, AI greeting
Taking Order	taking_order	Active order conversation
Upselling	upselling	AI suggesting add-ons
Confirming	confirming	Reviewing order with customer
Total Announcement	total_announcement	Announcing total
Pull Forward	pull_forward	Customer pulling to window
At Window	at_window	Customer at payment window
Payment	payment	Processing payment
Pickup	pickup	Handing off order
Complete	complete	Session finished
Cancelled	cancelled	Session cancelled

---

Lane Types

Type	Code	Description
Standard	standard	Single lane operation
Express	express	Limited menu, faster service
Dual	dual	Two-lane merged ordering

---

Start Drive-Thru Session

Request

POST /api/v1/voice/drive-thru/sessions
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "location_id": "loc-xyz789",
  "lane_id": "lane-1",
  "lane_number": 1,
  "lane_type": "standard",
  "language": "en",
  "car_description": "Blue sedan"
}

Response

{
  "session_id": "dt-sess-abc123",
  "voice_session_id": "voice-sess-xyz789",
  "lane_id": "lane-1",
  "lane_number": 1,
  "lane_type": "standard",
  "phase": "greeting",
  "arrival_time": "2026-01-23T14:30:00Z",
  "speaker_start_time": "2026-01-23T14:30:00Z",
  "greeting": {
    "text": "Good afternoon! Welcome to Acme Burgers. Ready to order?",
    "audio_url": "https://audio.olympuscloud.ai/tts/dt-greeting.mp3"
  }
}

---

Transition to Window

Request

POST /api/v1/voice/drive-thru/sessions/{session_id}/window
Authorization: Bearer {access_token}

Response

{
  "session_id": "dt-sess-abc123",
  "phase": "at_window",
  "window_arrival_time": "2026-01-23T14:32:15Z",
  "metrics": {
    "order_time_seconds": 135.0
  }
}

---

Complete Payment

Request

POST /api/v1/voice/drive-thru/sessions/{session_id}/payment
Authorization: Bearer {access_token}

---

Complete Pickup

Request

POST /api/v1/voice/drive-thru/sessions/{session_id}/complete
Authorization: Bearer {access_token}

Response

{
  "session_id": "dt-sess-abc123",
  "phase": "complete",
  "order_id": "order-12345",
  "order_total": 24.99,
  "metrics": {
    "greet_time_seconds": 5.0,
    "order_time_seconds": 135.0,
    "payment_time_seconds": 45.0,
    "food_time_seconds": 60.0,
    "total_time_seconds": 245.0,
    "target_time_seconds": 180.0,
    "exceeded_target": true
  }
}

---

Escalate to Human

Request

POST /api/v1/voice/drive-thru/sessions/{session_id}/escalate
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "reason": "Customer requested human assistance"
}

---

Get Speed of Service Metrics

Request

GET /api/v1/voice/drive-thru/metrics?location_id=loc-xyz789
Authorization: Bearer {access_token}

Response

{
  "location_id": "loc-xyz789",
  "average_total_time": 165.5,
  "average_order_time": 95.2,
  "average_payment_time": 35.8,
  "average_food_time": 55.3,
  "exceeded_target_count": 12,
  "total_completed": 156,
  "target_time_seconds": 180.0
}

---

Related Pages

• Voice Sessions - General session lifecycle
• NLU & Intent (Hey Maximus) - Drive-thru specific intents
• Streaming & Configuration - Audio streaming for drive-thru
• Offline Queue - Offline command queuing