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/*.

Offline Queue

Redis-backed command queuing for offline voice operations with automatic retry.

Base Path: /api/v1/voice/offline

---

Overview

When connectivity is lost, voice commands are queued locally and synced when online:

┌─────────────────────────────────────────────────────────────────┐
│                    Offline Queue Flow                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   Voice Command → Connectivity Check → Online? → Execute         │
│                         │                                        │
│                         ↓ Offline                                │
│                   ┌───────────┐                                  │
│                   │  Redis    │                                  │
│                   │  Queue    │                                  │
│                   └─────┬─────┘                                  │
│                         │                                        │
│            ┌────────────┼────────────┐                           │
│            ↓            ↓            ↓                           │
│       Critical       High        Normal                          │
│       (P1)          (P2)         (P3)                            │
│                         │                                        │
│                         ↓ Connectivity Restored                  │
│                   Execute by Priority                            │
└─────────────────────────────────────────────────────────────────┘

---

Command Priority Levels

Priority	Code	Value	Use Case
Critical	critical	1	Safety commands (86 an item)
High	high	2	Revenue-impacting (pricing)
Normal	normal	3	Standard commands
Low	low	4	Non-urgent commands

---

Command Status

Status	Code	Description
Pending	pending	Waiting to execute
Executing	executing	Currently running
Completed	completed	Successfully executed
Failed	failed	Failed after retries
Cancelled	cancelled	User cancelled
Expired	expired	TTL exceeded

---

Queue a Command

Request

POST /api/v1/voice/offline/queue
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "location_id": "loc-xyz789",
  "session_id": "voice-sess-abc123",
  "command_text": "Turn on Happy Hour pricing",
  "command_type": "enable_pricing",
  "command_data": {
    "pricing_profile_id": "happy-hour-01"
  },
  "confirmed": true,
  "priority": "high",
  "ttl_hours": 24,
  "device_id": "terminal-001"
}

Response

{
  "command_id": "cmd-xyz789",
  "status": "pending",
  "priority": "high",
  "expires_at": "2026-01-24T14:30:00Z",
  "queued_at": "2026-01-23T14:30:00Z"
}

---

Get Command Status

Request

GET /api/v1/voice/offline/queue/{command_id}
Authorization: Bearer {access_token}

Response

{
  "id": "cmd-xyz789",
  "tenant_id": "tenant-abc",
  "user_id": "user-123",
  "location_id": "loc-xyz789",
  "command_text": "Turn on Happy Hour pricing",
  "command_type": "enable_pricing",
  "status": "completed",
  "priority": "high",
  "attempt_count": 1,
  "max_retries": 3,
  "executed_at": "2026-01-23T14:35:00Z",
  "result": {
    "success": true,
    "pricing_enabled": true
  }
}

---

Get Pending Commands

Request

GET /api/v1/voice/offline/queue?status=pending&limit=50
Authorization: Bearer {access_token}

---

Cancel Command

Request

DELETE /api/v1/voice/offline/queue/{command_id}
Authorization: Bearer {access_token}

---

Sync from Device

Sync commands queued on an offline device.

Request

POST /api/v1/voice/offline/sync
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "device_id": "terminal-001",
  "commands": [
    {
      "device_id": "local-cmd-001",
      "user_id": "user-123",
      "location_id": "loc-xyz789",
      "command_text": "86 the salmon",
      "command_type": "86_item",
      "command_data": {"item_id": "salmon-01"},
      "confirmed": true,
      "priority": 1
    }
  ]
}

Response

{
  "synced_count": 1,
  "id_mapping": {
    "local-cmd-001": "cmd-server-xyz789"
  },
  "errors": []
}

---

Get Queue Statistics

Request

GET /api/v1/voice/offline/stats?location_id=loc-xyz789
Authorization: Bearer {access_token}

Response

{
  "pending_count": 5,
  "executing_count": 1,
  "completed_count": 245,
  "failed_count": 3,
  "total_processed": 248,
  "total_retries": 12,
  "average_execution_time_ms": 450.5,
  "oldest_pending_age_seconds": 120.0
}

---

Dead Letter Queue

Commands that failed after all retries.

Get Dead Letter Queue

GET /api/v1/voice/offline/dlq?limit=50
Authorization: Bearer {access_token}

Retry from Dead Letter Queue

POST /api/v1/voice/offline/dlq/{command_id}/retry
Authorization: Bearer {access_token}

---

Related Pages

• Voice Sessions - Session lifecycle management
• NLU & Intent (Hey Maximus) - Intent types and language processing
• Drive-Thru - Drive-thru lane management
• Streaming & Configuration - Audio streaming and config