Skip to main content
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/*.

NLU & Intent (Hey Maximus)

Natural Language Understanding engine powering Voice AI intent parsing, multi-language support, semantic menu search, and safety features.

Intent Types​

Standard Intents​

IntentDescriptionExample
add_itemAdd item to cart"I'll have a burger"
remove_itemRemove item from cart"Remove the fries"
modify_itemChange existing item"Make that a large"
confirm_orderConfirm current order"That's correct"
cancel_orderCancel entire order"Never mind, cancel"
check_priceAsk about pricing"How much is that?"
ask_recommendationRequest suggestions"What do you recommend?"
ask_ingredientsIngredient questions"What's on the burger?"
ask_allergenAllergen inquiries"Does that have nuts?"
checkoutReady to pay"That's all"
greetingCustomer greeting"Hi there"
thanksCustomer thanks"Thank you"
human_requestRequest human help"Can I speak to a person?"
unclearUnclear intent-

Drive-Thru Specific Intents​

IntentDescriptionExample
repeat_orderRepeat the order"Can you read that back?"
accept_upsellAccept upsell"Sure, add that"
decline_upsellDecline upsell"No thanks"
ask_totalAsk for total"What's my total?"
pull_forwardReady to pull forward"Okay, pulling up"
next_windowDirected to next window-

Multi-Language NLU​

Voice AI supports 6 languages with language-specific intent, quantity, and modifier patterns.

Supported Languages​

CodeLanguageExample Greeting
enEnglish"I'd like a burger"
esSpanish"Quisiera una hamburguesa"
frFrench"Je voudrais un burger"
deGerman"Ich möchte einen Burger"
ptPortuguese"Eu quero um hambúrguer"
zhChinese"我要一个汉堡"

Set Session Language​

POST /api/v1/voice/sessions
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "location_id": "loc-xyz789",
  "channel": "drive_thru",
  "lane": 1,
  "language": "es"
}

Language-Specific Patterns​

Quantity Detection:

LanguageWords Detected
Englishone, two, three, four, five
Spanishuno, dos, tres, cuatro, cinco
Frenchun, deux, trois, quatre, cinq
Germanein, zwei, drei, vier, fünf
Portugueseum, dois, três, quatro, cinco
Chinese一, 两, 三, 四, 五

Modifier Patterns:

TypeEnglishSpanishFrench
Remove"no onions", "without""sin cebolla""sans oignon"
Add"extra cheese", "add""extra queso", "con""extra fromage", "avec"
Side"on the side""a parte""à côté"
Size"small/medium/large""pequeño/mediano/grande""petit/moyen/grand"

Semantic menu search using Cloudflare Vectorize for natural language item matching.

How It Works​

Customer: "I want a big pepperoni with lots of cheese"
                      ↓
            Vector Embedding
                      ↓
           Vectorize Query
                      ↓
    Match: "Large Pepperoni Pizza" (score: 0.94)
    Modifiers: ["extra cheese"]

Search Menu Items​

POST /api/v1/voice/menu/search
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "query": "pepperoni pizza with extra cheese",
  "location_id": "loc-xyz789",
  "top_k": 5,
  "category": "pizza",
  "exclude_allergens": ["peanut", "tree nut"]
}

Response​

{
  "matches": [
    {
      "item_id": "pizza-01",
      "name": "Pepperoni Pizza",
      "category": "pizza",
      "price": 14.99,
      "score": 0.94,
      "description": "Classic pepperoni with mozzarella",
      "modifiers": ["extra cheese", "extra pepperoni", "thin crust"],
      "allergens": ["wheat", "dairy"]
    }
  ],
  "query_time_ms": 45.2,
  "search_method": "semantic"
}

Sync Menu for Location​

POST /api/v1/voice/menu/sync
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "tenant_id": "tenant-abc",
  "location_id": "loc-xyz789",
  "force": true
}

Response​

{
  "items_indexed": 156,
  "categories": ["burgers", "pizza", "sides", "drinks", "combos"],
  "sync_time_ms": 1250,
  "last_sync": "2026-01-23T15:30:00Z"
}

Modifier Types​

TypeCodeDescriptionExamples
AddaddAdd ingredient"extra cheese", "add bacon"
RemoveremoveRemove ingredient"no onions", "hold the pickles"
SubstitutesubstituteReplace ingredient"sub fries for salad"
QuantityquantityAmount modifier"light mayo", "extra sauce"
PreparationpreparationCooking style"well done", "grilled"
SizesizeSize selection"large", "medium"
SidesideOn the side"dressing on the side"

Noise Preprocessing​

Drive-thru audio preprocessing for noisy environments.

Handled Noise Patterns​

PatternExampleHandling
Noise markers[background noise]Removed
Hesitations"uh", "um", "er", "like"Removed
Repeated words"I I want"Deduplicated
Leading ellipses"...and a coke"Trimmed

Enable Noise Preprocessing​

Noise preprocessing is automatically enabled for drive-thru sessions. For other channels:

{
  "text": "[noise] I'd uh like um a burger",
  "is_drive_thru": true
}

After preprocessing: "I'd like a burger"

Allergen Detection​

Voice AI automatically detects allergen-related queries.

Detected Allergens​

AllergenDetected Phrases
Peanut"peanut allergy", "no peanuts"
Tree Nut"tree nut", "nut-free"
Dairy/Milk"dairy-free", "lactose", "no cheese"
Egg"egg allergy", "no eggs"
Wheat/Gluten"gluten-free", "celiac"
Soy"soy allergy"
Fish"fish allergy"
Shellfish"shellfish", "no shrimp"
Sesame"sesame allergy"

Response with Allergen Detection​

{
  "intent": {
    "name": "ask_allergen",
    "confidence": 0.95
  },
  "detected_allergens": ["peanut", "tree nut"],
  "response": {
    "text": "I see you mentioned a nut allergy. Let me check which items are safe for you.",
    "audio_url": "https://audio.olympuscloud.ai/tts/allergen-001.mp3"
  }
}