Skip to content · تخطَّ إلى المحتوى
نبرة Nabra
العربية

Using the API

Sessions and incremental updates

Build one record over several inputs: previous state + new input = updated state.

People rarely say everything at once. A session keeps the structured state between inputs: your app asks for what is missing, sends the answer with the same sessionId, and gets the updated record.

A booking in three inputs
# 1. Start a session (pins appointment_booking@1.0)
curl -X POST https://api.example.com/api/v1/sessions -H 'Content-Type: application/json' \
  -d '{"schema": "appointment_booking", "context": {"referenceTime": "2026-09-24T10:00:00+03:00"}}'
→ { "sessionId": "ses_Xy…", "missingFields": ["customerName", "phone", "date", "time"], … }

# 2. «بدي أحجز موعد مع الدكتور أحمد»
curl -X POST https://api.example.com/api/v1/voice/parse -F audio=@turn1.webm -F sessionId=ses_Xy…
→ data.doctor = "أحمد", missingFields = ["customerName", "phone", "date", "time"]

# 3. Your app asks «متى الموعد؟» — «بكرا الساعة خمسة المسا»
curl -X POST https://api.example.com/api/v1/voice/parse -F audio=@turn2.webm -F sessionId=ses_Xy…
→ data.doctor = "أحمد" (kept), data.date = "2026-09-25", data.time = "17:00",
  changedFields = ["date", "time"], missingFields = ["customerName", "phone"]

# 4. The user confirms or corrects in your UI
curl -X POST https://api.example.com/api/v1/sessions/ses_Xy…/review -H 'Content-Type: application/json' \
  -d '{"confirm": ["time"], "set": {"customerName": "سارة", "phone": "0781234567"}}'
→ { "complete": true, "data": { … } }

How inputs are merged

The merge is deterministic code, not the model:

  • A new verified value replaces the old one — the user corrected it («لا، مع الدكتور محمود»).
  • Silence never erases: a field the new input says nothing about keeps its value.
  • Something said but invalid fills an empty field as invalid (with heard), or marks an existing value for confirmation.
  • Each input is validated against everything said in the session, so «خليهم تلاتة» can update an item from an earlier input.
  • A phone number already placed is never re-assigned to another field by a later input.
  • Each result lists changedFields; the session keeps a history.

Review

POST /api/v1/sessions/{id}/review records what the user decided: confirm keeps a value and marks it confirmed, reject clears it, set stores a value the user typed or picked (checked for shape: a valid phone, a date, an allowed option).

Lifetime

Sessions are kept in memory for 30 idle minutes (SESSION_TTL_MINUTES), up to 20 inputs. DELETE forgets one immediately, transcripts included. Behind several instances, the session store moves to Redis or a database.