Response reference

Response reference

Every scope and endpoint in these docs tells you what you may call. This page tells you what comes back — the actual JSON, taken from the code that builds it.

Each example was derived from its construction site in the backend and then checked field-by-field against that site. Where an example and the code disagreed, the code won. The source file and line are cited under every entry.

Read this first — five things that catch people

1. The envelope, and where it nests deeper. Most REST handlers return {"success": true, "data": …}. Several nest one level further — data.objects, data.calls, data.agents, data.knowledgeBases. Destructure the level the example shows, not the one you expect.

2. Casing is not uniform across planes. The app surface is camelCase (agentId, createdAt). The dashboard and public /v1 surfaces are snake_case. A few shared helpers emit snake_case that a route then renames on the way out. The examples show the real casing per surface — trust them over intuition.

3. The bridge re-projects. window.telenow.* does not always hand your page the REST payload. Some ops hand-build a narrower or differently-cased object. Every op whose bridge shape differs from its REST shape says so.

4. Your fields are nested. An object row carries your data at row.data.<field>; a query tool returns results[i].data.<field>. Reaching for results[i].phone gets you undefined, silently.

5. Errors come in two flavours, and they are not interchangeable. A tool returns {"ok": false, "error": "…"} inside a successful call so the model can read it and recover mid-conversation. A REST route returns an HTTP error status with an error body. Handling one as the other means handling neither.

Quick index by scope

Developers usually arrive holding a scope. This maps each one to the section that answers it.

Tool returns — what the agent receives mid-call

The least-documented surface on the platform, and the one your prompt has to reason about. A declarative tool's result is fed straight back to the model as the tool output, so its shape decides what the agent can say next.

Confirm-before-execute gate — the envelope that replaces the real result

{
  "status": "confirmation_required",
  "instruction": "Do NOT treat this as done. Tell the caller you're about to send a payment link for ₹1499 to +919876543210, and ask them to confirm. Only after they clearly say yes, call this tool again with the same details. If they decline or change anything, do not proceed."
}

Easy to miss: for a tool flagged needs_confirmation, the FIRST call never reaches invoke_app at all (orchestration.rs:13567, :13572) — the model gets this instead of the handler's shape. The re-arm is keyed on tool name + a hash of the arguments, so re-calling with different args re-asks. Internal status is confirmation_pending (not success/error), which is what lands in tool_invocations and the tool.invoked webhook. The {summary} interpolation comes from spec.confirmation_summary(args).

Source: voice_ai_rust/src/services/orchestration.rs:12114-12152 (envelope :12141-12148)

Envelope contract — what the model actually receives

Several variants shown side by side — each top-level key labels a case (status code, method or provider) and is not part of any response.

{
  "1_cascade_internal_ChatMessage__and_openai_family_wire": {
    "_source": "orchestration.rs:13729-13735 (cascade voice) and :18170-18176 (text/WhatsApp/public API); sent verbatim by providers/llm/openai.rs:353",
    "role": "tool",
    "content": "{\"ok\":true,\"id\":\"7d3f9a1e-2c48-4b6a-9f10-5e8b2d4c7a63\",\"record\":{\"patient_name\":\"Asha Rao\",\"caller_number\":\"+919876543210\"}}",
    "tool_call_id": "call_9f2bA1",
    "name": "clinic_crm_book_appointment"
  },
  "2_anthropic_bedrock_cascade": {
    "_source": "providers/llm/anthropic.rs:169-181 — consecutive tool turns collapse into ONE user message; `name` is dropped",
    "role": "user",
    "content": [
      {
        "type": "tool_result",
        "tool_use_id": "toolu_01A9f2bA1",
        "content": "{\"ok\":true,\"id\":\"7d3f9a1e-2c48-4b6a-9f10-5e8b2d4c7a63\",\"record\":{\"patient_name\":\"Asha Rao\",\"caller_number\":\"+919876543210\"}}"
      }
    ]
  },
  "3_gemini_cascade": {
    "_source": "providers/llm/gemini.rs:565-570 + tool_content_to_response gemini.rs:485-491 — a JSON object passes through UNWRAPPED; a non-object becomes {\"result\": v}",
    "role": "user",
    "parts": [
      {
        "functionResponse": {
          "name": "clinic_crm_book_appointment",
          "response": {
            "ok": true,
            "id": "7d3f9a1e-2c48-4b6a-9f10-5e8b2d4c7a63",
            "record": { "patient_name": "Asha Rao", "caller_number": "+919876543210" }
          }
        }
      }
    ]
  },
  "4_s2s_openai_realtime": {
    "_source": "orchestration.rs:7770 -> providers/s2s/openai.rs:273-281 — no role, no name; call_id/output, nested under `item`",
    "type": "conversation.item.create",
    "item": {
      "type": "function_call_output",
      "call_id": "call_9f2bA1",
      "output": "{\"ok\":true,\"id\":\"7d3f9a1e-2c48-4b6a-9f10-5e8b2d4c7a63\",\"record\":{\"patient_name\":\"Asha Rao\",\"caller_number\":\"+919876543210\"}}"
    }
  },
  "5_s2s_gemini_live": {
    "_source": "orchestration.rs:7770 -> providers/s2s/gemini.rs:372-387 — the string is re-parsed and ALWAYS nested under response.result",
    "toolResponse": {
      "functionResponses": [
        {
          "id": "call_9f2bA1",
          "name": "clinic_crm_book_appointment",
          "response": {
            "result": {
              "ok": true,
              "id": "7d3f9a1e-2c48-4b6a-9f10-5e8b2d4c7a63",
              "record": { "patient_name": "Asha Rao", "caller_number": "+919876543210" }
            }
          }
        }
      ]
    }
  },
  "6_app_facing_event_not_the_model_envelope": {
    "_source": "orchestration.rs:9449-9458 emit_tool_invoked — camelCase, and `result` is an OBJECT not a string",
    "event": "tool.invoked",
    "sessionId": "b41c8e02-5a7d-4f19-9c33-2ad6e0f81b45",
    "agentId": "3f6a1d90-77c4-4e2b-8a51-9db0c4e73f12",
    "name": "clinic_crm_book_appointment",
    "arguments": { "patient_name": "Asha Rao" },
    "result": {
      "ok": true,
      "id": "7d3f9a1e-2c48-4b6a-9f10-5e8b2d4c7a63",
      "record": { "patient_name": "Asha Rao", "caller_number": "+919876543210" }
    },
    "status": "success",
    "latencyMs": 214
  },
  "7_app_tool_error_envelope": {
    "_source": "tool.rs:1421-1424 (row cap) — soft error stays ok:false inside a successful dispatch; a dispatcher Err becomes {\"error\": msg} at orchestration.rs:18146/18152",
    "soft": { "ok": false, "error": "app data store is full — cannot create more records" },
    "hard": { "error": "unknown tool: clinic_crm_book_appointment" }
  }
}

There is NO {success,data} wrapper anywhere on this surface — that is the REST convention only. The handler's JSON Value is stringified verbatim (result.to_string(), compact, no spaces) into the tool message content. Two consequences developers trip on: (1) a handler that returns a bare array or null reaches the model as the literal string null / [...]; (2) the platform decides status for logging purely by v.get("error").is_some() (orchestration.rs:13578, :7683, :18143) — so an {"ok":false,"error":…} app envelope IS classed "error", but {"results":[]} is classed "success". Key casing on this surface is MIXED and per-handler, not one convention: declarative app handlers emit snake_case (ok, record, created_at), while natives emit a mix (at_limit, volume_percent, row_count snake; toAgent, numberEnding, latencyMs camel).

On failure:

{"role":"tool","tool_call_id":"call_9f2bA1","name":"clinic_crm_book_appointment","content":"{\"error\":\"app tool 'clinic-crm' is not available to this agent\"}"}

Source: voice_ai_rust/src/services/orchestration.rs:13729-13735 (cascade voice), :18170-18176 (text/WhatsApp/public API), :7770 (s2s send_tool_result)

Flow tool NODE — the SAME handlers, re-projected into variables (differs)

// object.create returns {"ok":true,"id":"7d3f9a1e-…","record":{…}}
// but a flow tool NODE merges this into session variables instead:
{
  "_tool_status": "ok",
  "ok": true,
  "id": "7d3f9a1e-2c48-4b6a-9f10-5e8b2d4c7a63"
}

• This is the closest thing to a bridge re-projection on this surface, and it silently LOSES data. A deterministic flow tool node does not hand the JSON to a model — it flattens ONLY top-level String/Number/Bool values into session variables. So record (object) and results (array) are DROPPED entirely: after an object.query node no new variable appears at all, and after object.create you get only ok and id.
• WORSE: _tool_status is "ok" for ANY Ok(...) return, including the soft {ok:false,error:…} envelopes — so the row-cap refusal, "no matching record found", and the empty-filter refusal all route down the SUCCESS branch of a tool_result edge (edge match at services/flow.rs:1138-1142), with the refusal text flattened into an error variable. Only an anyhow bail sets _tool_status = "error". In a simulation the node never executes and just sets _tool_status="ok" (:24266-24274).

Source: voice_ai_rust/src/services/orchestration.rs:24284-24306 (flatten :24287-24298, _tool_status :24286/:24304)

tool.invoked webhook + tool.call debug-trace payload

{
  "__wire_shape_1__ tool.invoked webhook — orchestration.rs:9449-9458; this object IS the entire HTTP POST body (no {success,data} envelope; delivery metadata is in headers)": {
    "event": "tool.invoked",
    "sessionId": "c0a81f43-6d2e-4f7b-b1a9-8e5c3d4f2a11",
    "agentId": "b41e77c2-9d0a-4f35-8c62-1a7e5f3b90d4",
    "name": "clinic_crm_book_appointment",
    "arguments": { "patient_name": "Asha Rao", "slot": "2026-08-03T10:30:00+05:30" },
    "result": { "ok": true, "id": "7d3f9a1e-2c48-4b6a-9f10-5e8b2d4c7a63", "record": { "status": "booked" } },
    "status": "success",
    "latencyMs": 214
  },
  "__wire_shape_2__ tool.call debug-trace NDJSON line — payload orchestration.rs:13692-13701 (cascade) and :7726-7735 (s2s); type/seq/t_ms stamped flat by call_tracer.rs:312-326": {
    "corr": "t3:n=book_slot:g=1",
    "id": "call_9XkQm2ZrT4",
    "name": "clinic_crm_book_appointment",
    "args": { "patient_name": "Asha Rao", "slot": "2026-08-03T10:30:00+05:30" },
    "result": { "ok": true, "id": "7d3f9a1e-2c48-4b6a-9f10-5e8b2d4c7a63", "record": { "status": "booked" } },
    "status": "success",
    "error": null,
    "latency_ms": 214,
    "type": "tool.call",
    "seq": 42,
    "t_ms": 8137
  }
}

The webhook is camelCase (sessionId, agentId, latencyMs) while the result it carries keeps the handler's own casing — so a single payload mixes both conventions. result is the UNSTRINGIFIED Value here, unlike the model-facing tool message. status ∈ success | error | not_found | confirmation_pending. The debug-timeline event is a DIFFERENT shape from the same data: {"corr","id","name","args","result","status","error","latency_ms"} — snake_case latency_ms, args not arguments, plus id (the tool_call_id) and a nullable error string that the webhook does not carry. A deterministic flow tool node emits flow_tool.call instead, with {"corr","name","status","latency_ms","result"} and no args/id.

Source: voice_ai_rust/src/services/orchestration.rs:9439-9462 (webhook); :13692-13704 and :7725-7737 (debug trace tool.call)

app handler http (external tier) — passthrough

{
  "available": true,
  "slots": ["2026-08-03T10:30:00+05:30", "2026-08-03T11:00:00+05:30"],
  "clinic": "Andheri West"
}

NO platform envelope is added — whatever the developer's service returns is handed to the model verbatim, so the app owns this shape entirely. Two traps: (1) a 2xx response whose body is not valid JSON silently becomes Value::Null, and the model receives the literal string null — not an error; (2) if the service returns a top-level error key, the platform classes the call "error" purely on that (orchestration.rs:13578). The request your service receives is {"tool":"<wire name>","arguments":{…}} plus "caller" only when the agent consented (tool.rs:1667-1670, egress tier stripped at :1223-1234), signed x-telenow-signature: sha256=<hex>.

Source: voice_ai_rust/src/services/tool.rs:1692-1693 (serde_json::from_slice(&bytes).unwrap_or(Value::Null)); request built at :1667-1681

app handler object.create — success

{
  "ok": true,
  "id": "7d3f9a1e-2c48-4b6a-9f10-5e8b2d4c7a63",
  "record": {
    "patient_name": "Asha Rao",
    "phone": "+919845012345",
    "slot": "2026-08-03T10:30:00+05:30",
    "status": "booked",
    "caller_number": "+919845012345"
  }
}

record is the STORED row (row.data), not the model's arguments. It contains three merged layers, in this precedence: model args → author config.defaults (tool.rs:1384) → manifest objects[].fields[].default via config.field_defaults (tool.rs:1414-1418, built at app_manifest.rs:1530-1541) → the system-injected caller_number (tool.rs:1419-1421), which is written UNCONDITIONALLY when the call has a caller number and can never be overridden by the model. GOTCHA: create's record does NOT carry computed fields — apply_computed runs only in the query path (app_object_enrich.rs:273-274), so a field the app's own UI shows is absent here but present in object.query. id is the record uuid as a bare string, NOT nested under record.

Source: voice_ai_rust/src/services/tool.rs:1443 (Ok(json!({ "ok": true, "id": row.id, "record": row.data })))

app handler object.delete — success and not-found

{
  "ok": true,
  "deleted": true,
  "id": "7d3f9a1e-2c48-4b6a-9f10-5e8b2d4c7a63",
  "record": {
    "patient_name": "Asha Rao",
    "phone": "+919845012345",
    "slot": "2026-08-03T10:30:00+05:30",
    "status": "booked"
  }
}

Delete is the ONLY handler with a deleted key, and it is present on BOTH outcomes (true / false) alongside ok — do not treat deleted as a success discriminator on its own. record is the deleted row's data, returned so the agent can read back what it removed. Deletes the NEWEST matching record only, one per call (tool.rs:1623). The missing-match-value error here is the TERSE form — unlike object.update it does NOT list the args that arrived: {"error":"missing value for match field booking_ref"}. Note object.delete is fully supported (app_manifest.rs:843-844) even though the unsupported-kind message below forgets to list it.

On failure:

{
  "ok": false,
  "deleted": false,
  "error": "no matching record found"
}

Source: voice_ai_rust/src/services/tool.rs:1628-1641 (success :1638, not-found :1640); missing match value :1620-1622

app handler object.query — success

{
  "results": [
    {
      "id": "7d3f9a1e-2c48-4b6a-9f10-5e8b2d4c7a63",
      "data": {
        "patient_name": "Asha Rao",
        "phone": "+919845012345",
        "slot": "2026-08-03T10:30:00+05:30",
        "status": "booked",
        "caller_number": "+919845012345",
        "display_name": "Asha Rao — 3 Aug"
      },
      "created_at": "2026-07-29T09:14:22.481293Z"
    }
  ]
}

• NESTED WHERE YOU EXPECT FLAT: every stored field is under results[i].data.<field>, never results[i].<field>.
• NO ok KEY AT ALL — this is the one declarative handler with no ok; a reader (or a flow tool_result edge) that keys off ok sees undefined on the happy path. Only three keys survive per row — id, data, created_at — the AppObjectRow's org_id, app_id, object_type, created_by, updated_at are all dropped (row struct: db/app_objects.rs:13-22). created_at is chrono RFC3339 with microseconds and a Z suffix. data DOES include computed fields (display_name above) because the tool goes through app_object_enrich::query_enriched, not the raw store (tool.rs:1532). Relation <field>__expanded keys NEVER appear here: the tool passes expand: Default (empty) at tool.rs:1537-1540. Hard limit: 50, newest-first. Zero matches is {"results":[]} and is classed "success". Filtering is exact TEXT equality (data->>'k' = value, db/app_objects.rs:250-252), and args that are not declared stored fields are silently DROPPED from the filter (tool.rs:1452-1459).

Source: voice_ai_rust/src/services/tool.rs:1532-1548 (results built at :1544-1547)

app handler object.update — success

{
  "ok": true,
  "id": "7d3f9a1e-2c48-4b6a-9f10-5e8b2d4c7a63",
  "record": {
    "patient_name": "Asha Rao",
    "phone": "+919845012345",
    "slot": "2026-08-05T16:00:00+05:30",
    "status": "rescheduled",
    "caller_number": "+919845012345"
  }
}

Same shape as create. record is the FULL merged record after a shallow JSONB merge, not the patch — fields the model never mentioned are still present. Only the NEWEST record matching data->>match = value is touched (db/app_objects.rs:200). The match field is stripped from the patch (tool.rs:1583) and manifest handler.set constants are applied last and always win (tool.rs:1584-1588). Computed fields are NOT applied here either.

Source: voice_ai_rust/src/services/tool.rs:1599-1602; SQL data = data || $2 at db/app_objects.rs:204-211

app handler sandbox (gated) — success and failure

{
  "success — tool.rs:1713, `outcome.value` returned verbatim; keys are whatever the app's JS snippet returned, always a JSON object, NO envelope and NO `ok` field": {
    "total": 1770,
    "currency": "INR",
    "breakdown": { "base": 1500, "tax": 270 }
  },
  "failure — tool.rs:1714-1716, hand-built envelope; `status` is one of error|timeout|oom|invalid|busy (code_runner.rs:56), `error` is a ≤512-char diagnostic": {
    "ok": false,
    "status": "timeout",
    "error": "execution timed out"
  },
  "gated off (the DEFAULT — FEATURE_APP_SANDBOX unset) — tool.rs:1699-1701 bails, and the call site renders the Err as orchestration.rs:7687": {
    "error": "sandbox app tools are disabled (set FEATURE_APP_SANDBOX=true)"
  }
}

On success the JS return value is passed through RAW with no envelope — no ok, no wrapper. The snippet MUST return an object: a scalar, array, undefined, a function, or a circular value all become the failure envelope with "error":"snippet must return an object" (code_runner.rs:186-193). Args arrive in JS as the frozen global dv (alias vars). Failure envelope keys are ok/status/error — note status here is a SANDBOX status string, unrelated to the platform's success/error classification. status ∈ ok | error | timeout | oom | invalid | busy (code_runner.rs:56); busy means the concurrency semaphore was full, invalid means empty/oversized source or oversized inputs. Error text is capped and truncated on a UTF-8 boundary. When the feature flag is off the whole thing is instead an anyhow bail: {"error":"sandbox app tools are disabled (set FEATURE_APP_SANDBOX=true)"} (tool.rs:1699-1702), and a manifest with no code: {"error":"sandbox handler missing code"}.

On failure:

{
  "ok": false,
  "status": "timeout",
  "error": "execution timed out"
}

Source: voice_ai_rust/src/services/tool.rs:1710-1717 ("ok" => Ok(outcome.value)); CodeOutcome at services/code_runner.rs:55-62

native adjust_volume / set_language / opt_out — what the model sees

{
  "status": "adjusted",
  "volume_percent": 141,
  "at_limit": false,
  "note": "volume changed — repeat your last point and confirm it's better"
}

{
  "status": "language_set",
  "language": "Hindi",
  "note": "From now on reply ONLY in Hindi, whatever language the caller speaks. Briefly confirm the switch to the caller in Hindi now."
}

{
  "status": "opted_out",
  "note": "recorded — the caller will not be contacted again. Confirm that plainly, then close politely."
}

These three are DATA-ONLY natives (orchestration.rs:13614-13621): the tool loop continues and the model must speak afterwards — hence the note key, which is a behavioural INSTRUCTION to the model, not display text. volume_percent is integer milli/10, range 50–200 (100 = normal); at_limit is true at 500 or ≥1996 milli and swaps note for already at maximum volume — if the caller still can't hear, suggest they raise their phone or speaker volume / already at minimum volume. set_language.language is the RESOLVED display name, not the code the model sent, and its failure is {"error":"unrecognized language 'klingon' — retry with a plain language name like 'hindi', 'telugu', 'english'"}. opt_out takes NO arguments — the number is resolved server-side from the session row; its errors always state plainly that nothing was recorded.

Source: voice_ai_rust/src/services/orchestration.rs:25217-25226 (adjust_volume), :25280-25291 (set_language), :25232-25240 (opt_out)

native end_call / navigate — what the model sees

{ "status": "ending" }

{ "status": "navigating", "to": "node_collect_details" }

end_call returns a single key and nothing else — the hangup is DEFERRED to the post-loop teardown so the goodbye line drains first, so "ending" means armed, not hung up. navigate.to is the flow NODE ID, not the label the model passed. Navigate's failure is the terse {"error":"navigate: unknown target"} (:25154). Both are terminal natives: the tool loop breaks after them.

Source: voice_ai_rust/src/services/orchestration.rs:25116 (end_call), :25148-25157 (navigate)

native transfer — what the model sees

{
  "status": "transferring",
  "to": "+912261234567"
}

Natives never use ok — they use status (a per-kind verb string) plus kind-specific keys, and failures are the flat {"error": …} with no ok. to is the E.164 number actually dialled (the first non-DNC-suppressed number of the chosen label). Distinctive failures, verbatim: transfer tool has no destination configured; all transfer destinations are on the do-not-call list; plus the carrier error string on a failed bridge. On success the tool loop STOPS (terminal native, orchestration.rs:13676-13678) — the model gets this result but no further turn.

Source: voice_ai_rust/src/services/orchestration.rs:25050-25060 (success :25052)

native agent handoff — what the model sees

{
  "status": "handed_off",
  "mode": "transfer",
  "toAgent": "b41e77c2-9d0a-4f35-8c62-1a7e5f3b90d4"
}

camelCase toAgent sitting next to snake_case status/mode — the native surface is not internally consistent. mode is exactly "transfer" or "connect" (anything else in the manifest normalises to "transfer"). toAgent is the target agent uuid, not a label. The unknown-destination error echoes the RESOLVABLE labels so the model can retry: {"error":"unknown handoff destination \"billing\" — valid destinations: Sales, Support"} (orchestration.rs:25080-25084); with none configured: agent handoff tool has no target agent configured.

Source: voice_ai_rust/src/services/orchestration.rs:25092-25104 (success :25097-25099); mode resolution at services/tool.rs:506-513

native dataset lookup (structured KB) — what the model sees

{
  "result": [
    { "sku": "TN-4410", "name": "Wall mount bracket", "price": 1499, "in_stock": "yes" }
  ],
  "row_count": 1
}

result is polymorphic and row_count is NULL whenever it is not an array — read them together. Three shapes from the same tool: rows → result is an array of the raw dataset row objects (all cell values are STRINGS, they come from JSONB data), row_count = length; a bare aggregate → result is a NUMBER and row_count is null (e.g. {"result":143,"row_count":null}, dataset_query.rs:239); a grouped aggregate → result is [{"group":"Mumbai","value":42}] (dataset_query.rs:230-234). Hard LIMIT 20 rows. Failures are flat {"error": …}: could not understand the lookup arguments: <serde msg> (fails CLOSED — a filter missing op never degrades to an unfiltered read), unknown column: <name> / unsupported op: <op> / <func> needs a numeric column; '<col>' is not numeric from compile, and the deliberately vague could not run that lookup on the dataset for any DB error (the real sqlx detail goes to the log, never to the model).

Source: voice_ai_rust/src/services/dataset_query.rs:277-281 (json!({ "result": result, "row_count": row_count })); dispatched from orchestration.rs:25172-25182 and (text brain) :18124-18140

native follow-up scheduling — what the model sees

{
  "status": "scheduled",
  "at": "2026-07-29T17:00:00+05:30",
  "numberEnding": "2345"
}

The full callback number is NEVER returned — only numberEnding, the last 4 digits, deliberately so the number does not enter the LLM context (:25512-25522). at is when_display, which PRESERVES THE CALLER-LOCAL OFFSET the model supplied (not UTC) precisely so the model reads back the right wall-clock time. In a simulation the shape changes to {"status":"simulated","at":"…","note":"simulation — no real follow-up call was scheduled"} and nothing is persisted. Every failure is flat {"error": "<caller-facing sentence>"} and the sentences are instructions to the model, not diagnostics — e.g. follow-up calls only work on phone calls, and this is a web session — politely tell the caller you cannot schedule an automatic call-back from this channel; this call already has 3 pending follow-ups — do not schedule more; this number already has 2 pending follow-ups — do not schedule more; invalid atvalue "5pm" — send an ISO 8601 date-time WITH a timezone offset (e.g. 2026-07-04T17:00:00+05:30), or usein_minutes``.

Source: voice_ai_rust/src/services/orchestration.rs:25499-25536 (success :25528-25532); simulation branch :25400-25410

Unknown / unavailable tool name

{ "error": "unknown tool: book_appointmnt" }

Internal status is not_found, not error. On s2s there is a SECOND, kinder variant used when the name IS in the graph-wide tool union but not at the current node — the wire carries the union while dispatch is per-node: {"error":"this tool is not available at this step: 'refund_order' belongs to a different step of this conversation. Use only the tools listed in your current instructions, or navigate to the step that offers it."} (orchestration.rs:7704-7710). And a non-native, non-app tool named on an s2s call gets {"error":"tool 'x' (native kind None) is not available on speech-to-speech calls"} (:7673-7677) — again Rust {:?} formatting leaking into a model-facing string.

Source: voice_ai_rust/src/services/orchestration.rs:13588 & :18152 (cascade/text), :7691-7715 (s2s)

app handler http — failure envelopes

{
  "error": "app tool failed (404 Not Found): {\"message\":\"no such clinic\"}"
}

All five are anyhow::bail! → the flat {"error": …} wrap, never {ok:false}. Non-2xx interpolates reqwest's StatusCode Display ("404 Not Found") and the response body TRIMMED TO 300 CHARS (text.chars().take(300)), so a long vendor error is cut mid-JSON — expect unparseable fragments in that string. The other four, verbatim: app tool response exceeded 1 MB cap; external app tool missing base_url; app install has no signing secret; app tool url rejected: <ssrf reason>. A network timeout/connection failure surfaces as reqwest's own Display text under the same error key.

Source: voice_ai_rust/src/services/tool.rs:1687-1691 (non-2xx), :1684-1686 (1 MB cap), :1650 (base_url), :1666 (signing secret), :1662 (SSRF)

app handler object.create — row-cap refusal

{
  "ok": false,
  "error": "app data store is full — cannot create more records"
}

Verbatim string, no interpolation. This is a soft envelope (HTTP-less, Ok(...)), so the tool call "succeeds" at the transport level and only the error key marks it. The check FAILS CLOSED on a DB error while refreshing the cached count (app_quota.rs:135-138) — so a Postgres blip produces this exact same "store is full" text even when the app is nowhere near 100k rows. The count is cached for 60s per (org, app).

Source: voice_ai_rust/src/services/tool.rs:1423-1428; cap constant MAX_ROWS_PER_APP = 100_000 at services/app_quota.rs:109, check at :124-152

app handler object.query — the empty-filter refusal (two variants)

{
  "ok": false,
  "error": "no lookup value was provided — ask the caller for the detail this lookup needs (e.g. their phone number) and try again"
}

Fires only when the surviving filter is empty AND the tool has a real lookup key (a declared parameter or a handler.map target that is a stored field) — tool.rs:1477-1498. A genuine LIST/BROWSE tool with no stored-field parameter falls through to the bounded 50-row read instead of refusing. The two variants differ by a suffix appended inside the same error string when the manifest declares a non-empty handler.map; reproduce it exactly (note the sentence runs on with no space before (this tool…). Cause when you see the map variant: the call carries NO caller identity (web call, or withheld caller ID) — not a consent-toggle problem, because a query filter is a lookup position and lookup bypasses the consent toggle (tool.rs:1249-1255).

On failure:

{
  "ok": false,
  "error": "no lookup value was provided — ask the caller for the detail this lookup needs (e.g. their phone number) and try again (this tool normally uses the caller's own details, but this call has none — a web call, or a withheld caller ID — so ask the caller for it)"
}

Source: voice_ai_rust/src/services/tool.rs:1500-1525 (message at :1518-1524, declares_map hint at :1507-1517)

app handler object.update — no match / missing match value

Several variants shown side by side — each top-level key labels a case (status code, method or provider) and is not part of any response.

{
  "no_matching_record (tool.rs:1604)": {
    "ok": false,
    "error": "no matching record found"
  },
  "missing_match_value (tool.rs:1564-1580 -> orchestration.rs:13584) - NOTE: no `ok` key": {
    "error": "missing value for match field `appointment_id` — this tool received [caller_number, notes, phone]. The `match` field must be the name of an ARGUMENT the model fills (or a `handler.map` target), not just a field of the object."
  },
  "success, for contrast (tool.rs:1602)": {
    "ok": true,
    "id": "9f2c1b84-3d5e-4a17-9c60-7b1e2af03d55",
    "record": {
      "appointment_id": "APT-4821",
      "phone": "+14155550111",
      "status": "cancelled",
      "updated_at": "2026-07-29T11:42:07Z"
    }
  }
}

TWO DIFFERENT ENVELOPES for what reads like one failure. "no matching record found" is the soft {ok:false,error} envelope. A MISSING/blank match VALUE is an anyhow error instead — it never carries ok, and the model sees only {"error": "…"} (see error_example, transcribed from the anyhow! at tool.rs:1574-1579; the […] list is the sorted arg keys that actually arrived). A missing match KEY in the manifest is a third: {"error":"object.update handler missing match"} (tool.rs:1557).

On failure:

{
  "error": "missing value for match field `candidate` — this tool received [candidate_id, notes, stage]. The `match` field must be the name of an ARGUMENT the model fills (or a `handler.map` target), not just a field of the object."
}

Source: voice_ai_rust/src/services/tool.rs:1604 (no match); :1564-1580 (missing match value → anyhow::bail, wrapped into {"error": …} by orchestration.rs:13584)

app tool — pre-dispatch refusals (before any handler runs)

{
  "error": "app tool 'clinic-crm' is not available to this agent"
}

All flat {"error": …} (anyhow bails), no ok. Verbatim set: app tool '<app_id>' is not available to this agent (agent is not BOUND to that app — the guard against a hand-crafted flow node carrying another app's config.app_id); app tools are not available in this context; app tool missing config; app tool missing app_id; calling agent has no org; and per-handler object.<kind> handler missing object``. A DB failure inside insert/update/delete also surfaces here as sqlx's Display string under error.

Source: voice_ai_rust/src/services/tool.rs:1361-1363 (binding gate), :1337, :1341, :1345, :1354

app tool — unsupported handler kind

{
  "error": "unsupported app handler 'js' — supported: object.create / object.query / object.update (declarative), http (external), sandbox (gated)"
}

THE MESSAGE IS WRONG AND WILL MISLEAD YOU: it omits object.delete, which IS dispatched (tool.rs:1607) and IS in DECLARATIVE_HANDLER_KINDS (app_manifest.rs:843-844). Do not use this string as the authority on supported kinds. It fires most often for js, because the SDK's shipped JSON Schema offers js in editor autocomplete (app_preflight.rs:137-139) while the dispatcher only knows sandbox.

Source: voice_ai_rust/src/services/tool.rs:1719-1722

native tools — shared failure and skip envelopes

{
  "error": "skipped: an earlier tool in this turn already took over the call"
}

Every native failure is the flat {"error": …} — no ok, no status. Two envelopes exist that no handler produced: when a terminal native already ran this turn, later natives in the same batch are never dispatched and get skipped: an earlier tool in this turn already took over the call; when the call is already tearing down, a transfer/handoff gets skipped: the call is already ending. Both still reach the model as normal tool results so the protocol stays consistent. A stored native whose kind the dispatcher does not know: {"error":"unsupported native tool kind: Some(\"voicemail\")"} — note this interpolates Rust's {:?} Option debug format, quotes and Some(...) included.

Source: voice_ai_rust/src/services/orchestration.rs:13653-13662 (skips), :25293-25296 (unsupported kind)

Data API & the object store

Your app's records. Everything you stored lives under data — never flat on the row.

DELETE /api/app-data/:objectType/:id (external Data API — remove)

Scope: data:write — enforced ONLY for OAuth Bearer tokens; a static app key is NOT gated

{ "success": true }

• THERE IS NO data KEY AT ALL on success — this is the one CRUD route whose envelope is bare {success:true}. Destructuring const {data} = res gives undefined, not the deleted row.
• Contrast the dashboard proxy DELETE (routes/apps.rs:3351), which is byte-identical {success:true}, and the agent object.delete tool, which DOES return the deleted record.

On failure:

HTTP 404  {"success": false, "error": "record not found"}

Source: voice_ai_rust/src/routes/app_data.rs:370

GET /api/app-data/:objectType (external Data API — list)

Scope: data:read — enforced ONLY for OAuth Bearer tokens; a static app key is NOT gated

{
  "success": true,
  "data": {
    "objects": [
      {
        "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4",
        "orgId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
        "appId": "clinic-crm",
        "objectType": "patient",
        "data": { "first_name": "Asha", "phone": "+919876543210", "status": "active" },
        "createdBy": "api",
        "createdAt": "2026-07-29T09:14:22.481233Z",
        "updatedAt": "2026-07-29T09:14:22.481233Z"
      }
    ]
  }
}

• DOUBLE-NESTED: data.objects — res.data is an OBJECT with one key, not the array.
• NO nextCursor, NO total, NO hasMore on this route — unlike the dashboard proxy's list, which does return nextCursor. You cannot page the external Data API; you get one limit-sized window (default 100, hard max 500 via effective_limit, app_object_enrich.rs:25-36).
• RESERVED QUERY KEYS are swallowed and never become filters: limit, search, topK/topk, sort, dir, numeric, view, expand (app_data.rs:101-129). A field literally named sort or limit is unfilterable here.
• Every other query param becomes an EQUALITY filter with a STRING value (filter.insert(k, Value::String(v)), :126) — ?age=30 compares text, and operators ($gt/$in/…) are not expressible; use the dashboard proxy's POST /query for those.
• ?search= only re-ranks when the manifest declares the object semantic:true, and it silently falls through to the normal recency query otherwise (app_object_enrich.rs:228).
• ?view= names a manifest-declared saved view whose filter WINS over a caller filter on the same key (app_object_enrich.rs:250-257); an unknown view name is a silent no-op, not a 404.
• Scope reality: check_auth_scope is called with static_install_check=false (app_data.rs:92), so data:read is enforced ONLY when app.scopes is Some — i.e. an OAuth Bearer token. A static per-install app key passes unconditionally. The objects:<type> scope every manifest declares is NOT enforced anywhere in this file.

On failure:

HTTP 403  {"success": false, "error": "token does not include the data:read scope"}

Source: voice_ai_rust/src/routes/app_data.rs:148

GET /api/app-data/bridge (cross-app read catalog)

Scope: no scope gate — only the rate limit; both manifests + both installs decide

{
  "success": true,
  "data": {
    "grants": [
      { "providerAppId": "clinic-crm", "objectType": "patient", "access": "read" },
      { "providerAppId": "clinic-crm", "objectType": "appointment", "access": "read" }
    ]
  }
}

• data.grants, and each entry is exactly these three keys — camelCase providerAppId, and access is the hardcoded literal "read" (:187), the only access level the bridge supports (non-read dependencies are skipped at :171).
• An empty grants: [] is the normal answer for "provider not installed" or "provider stopped exposing it" — it is computed LIVE from both manifests on every call, so it shrinks the moment either side revokes.
• This route calls neither check_auth_scope nor bridge_authorize; it is discovery only.

Source: voice_ai_rust/src/routes/app_data.rs:184-192

GET /api/app-data/bridge/:providerAppId/:objectType (read another app's rows)

Scope: no scope gate — gated by BOTH manifests (consumer declares appDependencies read, provider exposes to you) + both installs live

{
  "success": true,
  "data": {
    "objects": [
      {
        "id": "5e8a1f30-7c62-4b8d-9a44-1d2e3f4a5b6c",
        "orgId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
        "appId": "clinic-crm",
        "objectType": "patient",
        "data": { "first_name": "Asha", "phone": "+919876543210" },
        "createdBy": "api",
        "createdAt": "2026-07-29T09:14:22.481233Z",
        "updatedAt": "2026-07-29T09:14:22.481233Z"
      }
    ]
  }
}

• Envelope matches the normal list (data.objects) but appId on every row is the PROVIDER's app id, not yours — do not key your cache on it assuming ownership.
• RAW ROWS, NO ENRICHMENT: no computed fields, no __expanded, no views, no ?search=. The comment at :208-209 says so explicitly — the provider's private views/relations don't cross the boundary. A field the provider's own UI shows (a computed display_name) is simply ABSENT here.
• Only equality filters + ?limit= (clamped 1..500 at :217, unlike the main list's 0-means-default).
• Two distinct 403 texts tell you WHICH half of the gate failed — consumer-side declaration vs provider-side exposure.

On failure:

HTTP 403  {"success": false, "error": "app 'clinic-crm' does not share 'patient' with your app"}
HTTP 403  {"success": false, "error": "your app did not declare a read dependency on 'patient' from 'clinic-crm'"}
HTTP 400  {"success": false, "error": "use the normal data API to read your own app's data"}

Source: voice_ai_rust/src/routes/app_data.rs:232 (rows fetched raw at :221 via db::app_objects::query, deliberately NOT query_enriched)

GET /api/orgs/:orgId/apps/:appId/objects/:objectType (dashboard proxy — list)

Scope: org membership (any role) — NOT objects:<type>, NOT data:read

{
  "success": true,
  "data": {
    "objects": [
      {
        "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4",
        "orgId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
        "appId": "clinic-crm",
        "objectType": "patient",
        "data": { "first_name": "Asha", "phone": "+919876543210", "display_name": "Asha Rao" },
        "createdBy": "7d1e6c90-3b48-4f2a-8c55-9e0a1b2c3d4e",
        "createdAt": "2026-07-29T09:14:22.481233Z",
        "updatedAt": "2026-07-29T09:14:22.481233Z"
      }
    ],
    "nextCursor": "2026-07-29T09:14:22.481233+00:00,c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4"
  }
}

• data.objects PLUS data.nextCursor — the external Data API has no cursor, this one does.
• nextCursor is null (present, not omitted) whenever the page came back short of limit, which is how you detect the end.
• CURSOR FORMAT GOTCHA: it is "<rfc3339>,<uuid>" built with created_at.to_rfc3339(), which emits +00:00 — NOT Z — even though every other timestamp in the same response serializes with Z. Pass it back verbatim as ?before=; do not normalize it.
• A full page ALWAYS yields a cursor even when it is exactly the last page — the next call just returns an empty array.
• Rows ARE enriched (query_enriched at :2314): computed fields present, but this route hardcodes ..Default::default() so view, expand and search are unavailable — use POST /query for those.
• limit default 200, clamp 1..500 (:2312).
• Read is membership-only; only the WRITE routes require owner/admin/developer.

Source: voice_ai_rust/src/routes/apps.rs:2329-2332

PATCH /api/app-data/:objectType/:id (external Data API — merge-update)

Scope: data:write — enforced ONLY for OAuth Bearer tokens; a static app key is NOT gated

{
  "success": true,
  "data": {
    "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4",
    "orgId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "appId": "clinic-crm",
    "objectType": "patient",
    "data": { "first_name": "Asha", "phone": "+919876543210", "status": "discharged" },
    "createdBy": "api",
    "createdAt": "2026-07-29T09:14:22.481233Z",
    "updatedAt": "2026-07-29T13:40:55.002881Z"
  }
}

• Same double-nesting as create: the updated record is at res.data.data.
• It is a jsonb MERGE (data = data || $5, db/app_objects.rs:143), so the returned data is the WHOLE merged record, not just your patch — top-level keys you omitted survive, keys you sent are overwritten wholesale (a nested object is REPLACED, not deep-merged).
• Sending null for a key stores JSON null, it does not remove the key.
• Raw row again — no computed fields, no expansions.
• 404 (not 400) when the id exists but under a different objectType — the UPDATE is scoped by org+app+type+id.

On failure:

HTTP 404  {"success": false, "error": "record not found"}

Source: voice_ai_rust/src/routes/app_data.rs:352

POST /api/app-data/:objectType (external Data API — create)

Scope: data:write — enforced ONLY for OAuth Bearer tokens; a static app key is NOT gated

{
  "success": true,
  "data": {
    "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4",
    "orgId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "appId": "clinic-crm",
    "objectType": "patient",
    "data": { "first_name": "Asha", "phone": "+919876543210" },
    "createdBy": "api",
    "createdAt": "2026-07-29T09:14:22.481233Z",
    "updatedAt": "2026-07-29T09:14:22.481233Z"
  }
}

• data IS THE ROW ITSELF here — not data.object, not data.objects[0]. So the record you posted comes back at res.data.data, one level deeper than most readers expect.
• The response is the RAW insert row: computed fields and expansions are NOT applied on create (no enrich call on this path), so a field your list reads back as display_name is absent from the create response.
• createdBy is always the literal string "api" on this route (:322).
• The unknown-object-type 400 only fires on a DEFINITE "not declared" — declares_object returns None (⇒ write allowed) when the manifest can't be loaded or parsed (app_object_enrich.rs:111-123), so a manifest blip fails OPEN.
• Body must be a JSON object or you get 400 "body must be a JSON object" (:290).

On failure:

HTTP 400  {"success": false, "error": "unknown object type 'candidates' — declare it under the manifest's objects[]"}
HTTP 413  {"success": false, "error": "app data store is full (max 100000 records per app)"}

Source: voice_ai_rust/src/routes/app_data.rs:331

POST /api/orgs/:orgId/apps/:appId/objects/:objectType (dashboard proxy — create)

Scope: org role owner | admin | developer (viewer/member are read-only) + objectType declared

{
  "success": true,
  "data": {
    "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4",
    "orgId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "appId": "clinic-crm",
    "objectType": "patient",
    "data": { "first_name": "Asha", "phone": "+919876543210" },
    "createdBy": "7d1e6c90-3b48-4f2a-8c55-9e0a1b2c3d4e",
    "createdAt": "2026-07-29T09:14:22.481233Z",
    "updatedAt": "2026-07-29T09:14:22.481233Z"
  }
}

• data is the row itself → the record you sent is at res.data.data.
• createdBy here is the ACTING USER's uuid as a string (:3293), unlike the external API's literal "api" — same column, different meaning per surface.
• Raw insert row: no computed fields on the create/update response even though the list route materializes them.
• Role gate is stricter than the read: a member/viewer gets 403 on create/update/delete but 200 on list/query.

On failure:

HTTP 413  {"success": false, "error": "app data store is full (max 100000 records per app)"}

Source: voice_ai_rust/src/routes/apps.rs:3309 (PATCH twin at :3333)

POST /api/orgs/:orgId/apps/:appId/objects/:objectType/change-ticket

Scope: org membership + objectType declared (ensure_app_object)

{
  "success": true,
  "data": {
    "ticket": "9c2f0a7b41d84e6cb3f5d0a19e77c412",
    "wsUrl": "wss://app.telenow.ai/ws/object-changes?ticket=9c2f0a7b41d84e6cb3f5d0a19e77c412"
  }
}

• ticket is a DASHLESS 32-hex uuid (Uuid::new_v4().simple(), :3173) — not the canonical dashed form; treat it as an opaque string.
• wsUrl already contains the ticket as a query param — just open it, don't re-append. Scheme is wss:// unless x-forwarded-proto is literally "http" (routes/calls.rs:869-891).
• Single-use, 30s TTL in Redis (vai:objchange:{ticket}), consumed by GETDEL on connect — a second connect with the same ticket fails.

Source: voice_ai_rust/src/routes/apps.rs:3188-3191

POST /api/orgs/:orgId/apps/:appId/objects/:objectType/query (dashboard proxy — filtered/sorted read)

Scope: org membership + app installed & live + objectType declared (ensure_app_object)

{
  "success": true,
  "data": {
    "objects": [
      {
        "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4",
        "orgId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
        "appId": "clinic-crm",
        "objectType": "appointment",
        "data": {
          "patient_id": "5e8a1f30-7c62-4b8d-9a44-1d2e3f4a5b6c",
          "slot_start": "2026-07-30T10:30:00Z",
          "status": "booked",
          "patient_id__expanded": { "first_name": "Asha", "phone": "+919876543210" }
        },
        "createdBy": "agent:9a3d5c71-0f28-4e6b-b1a7-c8d9e0f1a2b3",
        "createdAt": "2026-07-29T09:14:22.481233Z",
        "updatedAt": "2026-07-29T09:14:22.481233Z"
      }
    ],
    "nextCursor": null
  }
}

• Identical envelope to the GET list (data.objects + data.nextCursor) — the difference is entirely in the REQUEST.
• nextCursor is FORCED to null whenever you passed orderBy OR view (:2422) — sorted and view results are NOT pageable, so a sorted query silently caps at limit (default 200, max 500) with no signal that more exist.
• Request keys are camelCase (orderBy, countOnly) — QueryBody carries rename_all="camelCase" (:2346); order_by in the body is silently ignored.
• filter values may be scalars (equality) or operator objects: $eq $ne $gt $gte $lt $lte $in $contains (db/app_objects.rs:301-377). $gt-family compares NUMERICALLY only when the JSON operand is a number, otherwise as text (ISO dates sort correctly as text). A malformed $in (operand not an array) matches NOTHING by design; an UNKNOWN operator is silently ignored, so {"$like":"x"} returns everything.
• expand embeds at data.<field>__expanded (max 8 fields, 500 ids each).
• search needs the object declared semantic:true, else it is ignored and you get a normal recency query.

On failure:

HTTP 400  {"success": false, "error": "unknown object type 'patients'"}
HTTP 404  {"success": false, "error": "app is not installed"}

Source: voice_ai_rust/src/routes/apps.rs:2427-2430 (request body struct at :2345-2370)

POST /api/orgs/:orgId/apps/:appId/objects/:objectType/query with {"countOnly": true}

Scope: org membership + app installed & live + objectType declared

{ "success": true, "data": { "count": 42 } }

• SAME URL as the query route — the body flag switches the entire response shape. data.objects is ABSENT (not empty), data.nextCursor is absent, data.count is a number.
• countOnly RETURNS EARLY BEFORE ENRICHMENT (:2385-2390), so it ignores view, expand, search, orderBy and limit entirely and counts the RAW filter against the whole (org, app, type) partition. A count taken with a view will NOT match the row count that same view returns.
• The count is unlimited — it is a real COUNT(*), not clamped to 500 like the row read.

Source: voice_ai_rust/src/routes/apps.rs:2389

The AppObject row — the unit every objects endpoint returns

{
  "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4",
  "orgId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "appId": "clinic-crm",
  "objectType": "patient",
  "data": {
    "first_name": "Asha",
    "last_name": "Rao",
    "phone": "+919876543210",
    "status": "active",
    "doctor_id": "a71c04e8-92b5-4d3f-8e10-6b2f9c4d7a55",
    "display_name": "Asha Rao",
    "doctor_id__expanded": { "name": "Dr. Mehta", "dept": "cardiology" }
  },
  "createdBy": "api",
  "createdAt": "2026-07-29T09:14:22.481233Z",
  "updatedAt": "2026-07-29T11:02:07.930114Z"
}

• TWO CASING PLANES IN ONE OBJECT. The envelope is camelCase (id/orgId/appId/objectType/createdBy/createdAt/updatedAt) because of rename_all="camelCase" on AppObjectRow. The keys INSIDE data are whatever the app stored — the shipped manifests use snake_case (first_name, doctor_id), and nothing renames them.
• EVERYTHING YOUR APP STORED IS UNDER data, never flat on the row: row.data.phone, not row.phone.
• Computed fields are MATERIALIZED INTO data (app_object_enrich.rs:299), so display_name is indistinguishable from a stored field in the response — it is recomputed from a snapshot on every read and any value you PATCH into it is overwritten.
• Relation expansion lands at data.<field>__expanded (app_object_enrich.rs:459 builds the key), NOT at row.<field>__expanded and not replacing the id field — to-one gives an object (null if the target is gone), to-many gives an array, and the array is silently SHORTER than the id array when a referenced row was deleted (:472-480 filter_map drops misses). Only the target row's data is embedded — no nested id/createdAt.
• createdBy is a provenance TAG, not always a user id: "api" for the external Data API (routes/app_data.rs:322), the user's uuid string for the dashboard proxy (routes/apps.rs:3293), "agent:<agentUuid>" for in-call tools (services/tool.rs:1427), "inbound-hook" for webhook writes (routes/app_hooks.rs:127), and null for public-link writes (routes/public_links.rs:479).
• The frontend's own AppObject TS interface (voice_ai_frontend/src/api/apps.ts:190-197) is INCOMPLETE — it omits orgId and updatedAt, both of which the server always sends.

Source: voice_ai_rust/src/db/app_objects.rs:11-22 (struct AppObjectRow, #[serde(rename_all="camelCase")]); computed inserted at voice_ai_rust/src/services/app_object_enrich.rs:299; expansion inserted at :470 and :479

WebSocket /ws/object-changes — one text frame per change

Scope: the single-use ticket from change-ticket (which required org membership)

{ "event": "created", "objectType": "patient", "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4", "data": { "first_name": "Asha", "phone": "+919876543210" } }

{ "event": "deleted", "objectType": "patient", "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4", "data": null }

• NO success envelope — the frame IS the payload, unlike every REST response on this surface.
• Exactly four keys. event is one of "created" | "updated" | "deleted" (&'static str).
• data HERE IS NOT THE ROW — it is only the row's data object (the stored fields), with NO id/orgId/appId/createdAt wrapper. The record id lives in the sibling id key. So a frame handler reads frame.id + frame.data.phone, while a REST handler reads row.id + row.data.phone — same nesting for the fields, different for the id.
• data is null on "deleted" (and only then).
• FRAMES ARE UNENRICHED: publish() is called from the db layer with the row straight off RETURNING, before app_object_enrich runs — so computed fields and __expanded are ABSENT from a frame but PRESENT in the list response for the same record. Don't diff one against the other.
• "updated" frames carry the full merged row data, not the patch.
• Frames are dropped (not buffered) for a lagging client — RecvError::Lagged is skipped silently at :84-87.

Source: voice_ai_rust/src/websocket/object_change_stream.rs:73-78 (frame built at db chokepoints voice_ai_rust/src/db/app_objects.rs:46, :122, :154, :181, :243)

object.create / object.update / object.delete (declarative agent tools)

Scope: manifest-declared tool; no data:* scope check on this path

// object.create and object.update (success):
{ "ok": true, "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4", "record": { "first_name": "Asha", "phone": "+919876543210", "status": "active", "caller_number": "+919876543210" } }

// object.delete (success):
{ "ok": true, "deleted": true, "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4", "record": { "first_name": "Asha", "phone": "+919876543210" } }

• The stored fields come back under record here — a THIRD name for the same thing (data on REST/bridge, data inside object.query results, record on these three). All in-band at HTTP 200: ok:false is the failure signal, there is no success key and no non-2xx.
• object.delete carries BOTH ok and deleted, and returns the deleted row's fields — unlike both REST DELETEs, which return nothing.
• record is the RAW stored data (no computed fields), and on create it includes server-injected keys the model never sent: the object's manifest field_defaults (:1414-1419) and caller_number, force-set from the trusted caller (:1420-1422).
• update/delete locate the NEWEST row matching handler.match — they are single-record ops, never bulk.

On failure:

{ "ok": false, "error": "no matching record found" }                      // object.update miss
{ "ok": false, "deleted": false, "error": "no matching record found" }     // object.delete miss
{ "ok": false, "error": "app data store is full — cannot create more records" }  // object.create at the row cap

Source: voice_ai_rust/src/services/tool.rs:1442 (create), :1602 and :1604 (update), :1638 and :1640 (delete)

object.query (declarative agent tool over the same store)

Scope: manifest-declared tool; no data:* scope check on this path

{
  "results": [
    {
      "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4",
      "data": { "first_name": "Asha", "phone": "+919876543210", "display_name": "Asha Rao" },
      "created_at": "2026-07-29T09:14:22.481233Z"
    }
  ]
}

• THE ONE snake_case SHAPE ON THIS SURFACE: created_at, not createdAt — it is hand-built with json! and never touches AppObjectRow's serde. orgId/appId/objectType/updatedAt/createdBy are all DROPPED.
• NO success and NO ok on the happy path — just {results:[…]}; but the two failure paths DO return {ok:false,error} at 200, so a consumer must check for results rather than for ok.
• FIELDS ARE UNDER results[i].data — results[0].data.phone, never results[0].phone. This is the single most common mis-destructure on the object store.
• Rows ARE enriched (query_enriched, :1529-1543), so computed fields appear; expand is not requested, so __expanded never does.
• Hard-capped at 50 rows (:1540) with no cursor and no total.
• Args are filtered to the tool's DECLARED fields before becoming the filter (:1450-1458) — an arg that isn't a stored field is dropped, not matched.

On failure:

{ "ok": false, "error": "no lookup value was provided — ask the caller for the detail this lookup needs (e.g. their phone number) and try again" }

Source: voice_ai_rust/src/services/tool.rs:1545-1548

telenow.data.count(objectType, query) — UI bridge

Scope: none

{ "count": 42 }

• RESOLVES TO AN OBJECT, NOT A NUMBER. const n = await telenow.data.count('patient') gives {count: 42} — n + 1 is the string "[object Object]1". Use (await telenow.data.count('patient')).count. This is the one bridge data op that does NOT flatten what the REST envelope gave it: countAppObjects unwraps {success,data} to {count} and the host passes that through verbatim.
• The 2nd arg is the filter and is sent as {filter, countOnly:true} — same countOnly early-return, so view/expand/search/limit are ignored.

Source: voice_ai_frontend/src/components/apps/AppPageHost.tsx:635; voice_ai_frontend/src/api/apps.ts:850-861

telenow.data.create(objectType, body) / .update(objectType, id, body) — UI bridge

Scope: none at the bridge; the server still requires org role owner | admin | developer

{
  "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4",
  "orgId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "appId": "clinic-crm",
  "objectType": "patient",
  "data": { "first_name": "Asha", "phone": "+919876543210" },
  "createdBy": "7d1e6c90-3b48-4f2a-8c55-9e0a1b2c3d4e",
  "createdAt": "2026-07-29T09:14:22.481233Z",
  "updatedAt": "2026-07-29T09:14:22.481233Z"
}

• BRIDGE DIFFERS FROM REST: REST gives {success, data:<row>}; the bridge resolves to the ROW directly (unwrap() strips the envelope, api/apps.ts:1052). Your stored fields are at row.data.* — one .data here, two on REST.
• Raw row: no computed fields on the create/update reply even though list() shows them for the same record. Re-list (or recompute locally) if your UI renders a computed field right after a write.

On failure:

the Promise REJECTS with `new Error("your role does not permit this action")` or with the server's error string

Source: voice_ai_frontend/src/components/apps/AppPageHost.tsx:637 and :640; voice_ai_frontend/src/api/apps.ts:1046-1065

telenow.data.list(objectType, query, opts) — UI bridge

Scope: none — the bridge treats an app's own objects as always-allowed (no need() call)

[
  {
    "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4",
    "orgId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "appId": "clinic-crm",
    "objectType": "patient",
    "data": { "first_name": "Asha", "phone": "+919876543210", "display_name": "Asha Rao" },
    "createdBy": "7d1e6c90-3b48-4f2a-8c55-9e0a1b2c3d4e",
    "createdAt": "2026-07-29T09:14:22.481233Z",
    "updatedAt": "2026-07-29T09:14:22.481233Z"
  }
]

• BRIDGE DIFFERS FROM REST. REST returns {success, data:{objects, nextCursor}}; the bridge resolves to the BARE ARRAY. The host unwraps the envelope and then takes .objects ((await queryAppObjects(...)).objects, :633). Await it and iterate directly — there is no .data, no .objects.
• nextCursor IS DISCARDED (:633) and the opts type (:565-571) has no before, so THE BRIDGE CANNOT PAGE. Raise opts.limit (server max 500) or you silently see only the first page.
• It POSTs to the /query route, not the GET list — so list() gets operators, sort, view, expand and search even though it is named "list".
• ARGUMENT SHAPE TRAP: the 2nd arg is the FILTER ONLY (it becomes filter, :626); sort/limit/view/expand/search go in the 3rd arg opts. Passing {limit: 50} as the 2nd arg filters on a stored field called "limit" and returns nothing.
• Row shape is otherwise identical to REST, computed + __expanded included.

Source: voice_ai_frontend/src/components/apps/AppPageHost.tsx:624-633 (SDK stub at :210); underlying call voice_ai_frontend/src/api/apps.ts:836-847

telenow.data.remove(objectType, id) — UI bridge

Scope: none at the bridge; the server still requires org role owner | admin | developer

{ "ok": true }

• HAND-BUILT BY THE BRIDGE, NOT FROM THE SERVER. The host awaits deleteAppObject, THROWS AWAY the server's {success:true}, and synthesizes {ok:true} (:644). So this is the only place on the whole object surface where the truthiness key is ok rather than success — and it is a client-side constant, never evidence of what the server said beyond "it did not throw".
• The deleted row is not returned anywhere on this path.

Source: voice_ai_frontend/src/components/apps/AppPageHost.tsx:643-644

telenow.data.subscribe(objectType, onChange) — UI bridge realtime

Scope: none at the bridge (same trust as data.list); ticket mint requires org membership

// resolves to an unsubscribe function:
const off = await telenow.data.subscribe('patient', (f) => { /* f is the frame below */ });
// each onChange call receives, verbatim:
{ "event": "updated", "objectType": "patient", "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4", "data": { "first_name": "Asha", "status": "discharged" } }

• The awaited value is a FUNCTION (unsubscribe), not data — the underlying RPC's {streamId} never reaches your code.
• The callback argument is the raw WS frame, forwarded verbatim by the host (data: frame, :1004), so it carries the same four keys and the same caveats as the WS entry: data is the stored-fields object only, null on "deleted", and UNENRICHED (no computed, no __expanded) — so a subscribe-driven list will lose the computed fields a list() put there unless you recompute.
• Frames arrive on a separate postMessage channel keyed by stream, not by reply id (:188), so they never resolve a pending RPC.

Source: voice_ai_frontend/src/components/apps/AppPageHost.tsx:987-1010 (host relay) and :217-225 (SDK stub, which swaps the RPC's {streamId} for the unsubscribe closure)

Data-API rate limit (429) and row cap (413)

HTTP 429
{ "success": false, "error": "Data API rate limit reached — slow down", "retryAfter": 1 }

HTTP 413
{ "success": false, "error": "app data store is full (max 100000 records per app)" }

• 429 is the ONLY object-surface error with a third key: retryAfter, an integer in SECONDS, camelCase in the body (there is no Retry-After header from this arm). It is always 1 for the Data API.
• The 429 gate runs FIRST on every /api/app-data route, before auth scope checks, and is per-(org, app).
• 413 (PAYLOAD_TOO_LARGE) is the row-cap signal, not a body-size signal — the number in the message is interpolated from the constant, so it moves if the cap moves. It fires on both create paths (external :311 and dashboard proxy voice_ai_rust/src/routes/apps.rs:3288); the agent tool instead returns an in-band {ok:false,error:"app data store is full — cannot create more records"} at 200.

Source: 429 constructed at voice_ai_rust/src/routes/app_data.rs:54-58, serialized at voice_ai_rust/src/error.rs:112-124; 413 at voice_ai_rust/src/routes/app_data.rs:311-314 (cap constant MAX_ROWS_PER_APP = 100_000, voice_ai_rust/src/services/app_quota.rs:109)

Standard REST error envelope (all object routes)

Several variants shown side by side — each top-level key labels a case (status code, method or provider) and is not part of any response.

{
  "title": "Standard REST error envelope (app object routes)",
  "envelope_construction_site": "voice_ai_rust/src/error.rs:151",
  "envelope_shape": { "success": false, "error": "<message string>" },
  "notes": "Flat, exactly two keys. The wire string is the raw message passed to the AppError variant - the `not found: {0}` / `bad request: {0}` Display prefixes are NOT used by the response body.",
  "dashboard_proxy_object_routes": {
    "route_prefix": "/api/orgs/:orgId/apps/:appId/objects/:objectType",
    "404_record_not_found": {
      "status": 404,
      "from": "voice_ai_rust/src/routes/apps.rs:3327 (update_object), :3347 (delete_object)",
      "body": { "success": false, "error": "record not found" }
    },
    "404_app_not_installed": {
      "status": 404,
      "from": "voice_ai_rust/src/routes/apps.rs:3262 (ensure_app_object)",
      "body": { "success": false, "error": "app is not installed" }
    },
    "400_body_not_object": {
      "status": 400,
      "from": "voice_ai_rust/src/routes/apps.rs:3284 (create_object), :3322 (update_object)",
      "body": { "success": false, "error": "body must be a JSON object" }
    },
    "400_unknown_object_type": {
      "status": 400,
      "from": "voice_ai_rust/src/routes/apps.rs:3265 (ensure_app_object)",
      "body": { "success": false, "error": "unknown object type 'patient'" }
    },
    "403_write_role_gate": {
      "status": 403,
      "from": "voice_ai_rust/src/routes/apps.rs:3281/3319/3342 -> voice_ai_rust/src/services/org.rs:1583-1586",
      "applies_to": "create / update / delete",
      "body": { "success": false, "error": "this action requires one of: owner, admin, developer" }
    },
    "403_not_a_member": {
      "status": 403,
      "from": "voice_ai_rust/src/routes/apps.rs:2382/3169 (require_member) -> voice_ai_rust/src/services/org.rs:1551",
      "applies_to": "query / count / change-ticket",
      "body": { "success": false, "error": "not a member of this organization" }
    },
    "no_objects_scope_403": "There is no `objects:<type>` scope check on any object route. `ensure_app_scope` (apps.rs:2436-2469) is never called with an `objects:*` scope, and the UI bridge marks object CRUD 'always allowed' (AppPageHost.tsx:612-644). `objects:patient` is install-consent metadata only."
  },
  "app_key_data_api_object_routes": {
    "route_prefix": "/api/app-data/:objectType",
    "403_oauth_token_scope": {
      "status": 403,
      "from": "voice_ai_rust/src/routes/app_data.rs:74",
      "body": { "success": false, "error": "token does not include the data:read scope" }
    },
    "403_static_key_scope": {
      "status": 403,
      "from": "voice_ai_rust/src/routes/app_data.rs:805-807",
      "body": { "success": false, "error": "app did not declare the files:read scope" }
    },
    "429_rate_limited": {
      "status": 429,
      "from": "voice_ai_rust/src/routes/app_data.rs:52-56 -> voice_ai_rust/src/error.rs:112-124",
      "note": "Extra camelCase `retryAfter` key on top of the standard envelope.",
      "body": { "success": false, "error": "Data API rate limit reached — slow down", "retryAfter": 1 }
    }
  },
  "scope_denial_403_actual_wording_and_routes": {
    "status": 403,
    "from": "voice_ai_rust/src/routes/apps.rs:2463-2467 (ensure_app_scope)",
    "reachable_from": "ai:llm (apps.rs:2483, 2940), files:read (2500), links:write/read (2518, 2532, 2544), agents:read (2590), agents:write (2626), agent-config read (2840), kb:read (2962, 2996), calls:transcribe:live (3076), members:read (3119), user:profile (3120) - NOT from object routes",
    "body": { "success": false, "error": "this install has not granted the kb:read scope. If the app's current manifest declares it, the org is still on an older installed version — upgrade the app in Settings → Apps to grant the new scopes" }
  },
  "envelope_variants_that_add_a_key": {
    "401_jwt": {
      "from": "voice_ai_rust/src/error.rs:88-92",
      "body": { "success": false, "error": "Access token expired", "code": "token_expired" }
    },
    "403_with_code": {
      "from": "voice_ai_rust/src/error.rs:97-103 (AppError::ForbiddenCode)",
      "body": { "success": false, "error": "support write access has expired", "code": "support_write_revoked" }
    },
    "502_provider": {
      "from": "voice_ai_rust/src/error.rs:133-144",
      "body": { "success": false, "error": "callback_method requires a valid URL", "code": "provider_error" }
    }
  },
  "ui_bridge_reprojection": {
    "from": "voice_ai_frontend/src/components/apps/AppPageHost.tsx:1042 with voice_ai_frontend/src/utils/error.ts:13-21",
    "note": "An app running inside the sandboxed iframe NEVER sees the REST envelope. The host catches the axios error, pulls `response.data.error`, and posts back a different shape - `success` is replaced by `ok` and the HTTP status is dropped.",
    "rest_shape": { "success": false, "error": "record not found" },
    "bridge_shape": { "source": "telenow-host", "id": "4f2c1e90-9a3c-4b21-8f77-1d0a6b5e2c31", "ok": false, "error": "record not found" },
    "bridge_success_shape_for_contrast": { "source": "telenow-host", "id": "4f2c1e90-9a3c-4b21-8f77-1d0a6b5e2c31", "ok": true, "data": {} }
  }
}

• Two keys only: success:false and error (a human string). There is NO code on these — code appears only for JWT failures (error.rs:90), ForbiddenCode (:100) and provider errors (:140), none of which the object routes raise.
• error is a SENTENCE, not an enum — never branch on its text; branch on the HTTP status.
• Any unmapped internal failure collapses to HTTP 500 {"success":false,"error":"Something went wrong"} (error.rs:147) — a DB error on a query looks identical to a panic.

Source: voice_ai_rust/src/error.rs:151 (generic arm); 403 text at voice_ai_rust/src/routes/apps.rs:2463-2467

UI-bridge failure frame (postMessage) — what an app page actually sees

// wire frame the host posts back into the iframe:
{ "source": "telenow-host", "id": "r7", "ok": false, "error": "record not found" }

// what your code sees: the Promise rejects
try { await telenow.data.update('patient', id, { status: 'x' }); }
catch (e) { e.message === 'record not found'; }

• THE BRIDGE'S SUCCESS KEY IS ok, THE REST SURFACE'S IS success — different words for the same idea on the two halves of the same feature. You almost never see the frame: the SDK resolves d.data on ok and rejects new Error(d.error) otherwise (:191).
• The rejection message is a flattened STRING — the HTTP status, and any retryAfter, are LOST crossing the bridge, so an app page cannot distinguish 429 from 404 except by matching text.
• Bridge-local failures use the same channel and are indistinguishable from server ones: "objectType required", "recordId required" (:620, :639, :642) and "your role does not permit this action" (:540) never reached the network at all.

Source: frame built at voice_ai_frontend/src/components/apps/AppPageHost.tsx:1042 (success twin at :1040); turned into a rejection by the injected SDK at :191

Calls & post-call analysis

Call history, one call in full, and the analysis document.

CallAnalysis — the analysis object (every field)

Scope: served inside calls:read / calls:read:org responses

{
  "sessionId": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
  "orgId": "c81b0f47-2e6a-4d3b-8f19-5a7c6e2d40b1",
  "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
  "status": "done",
  "summary": "Caller rescheduled a dental cleaning from Tue 29 Jul to Tue 4 Aug 11:00; SMS confirmation promised.",
  "sentiment": "positive",
  "sentimentScore": 0.62,
  "disposition": "appointment_rescheduled",
  "actionItems": ["Send SMS confirmation for 2026-08-04 11:00"],
  "customData": { "patient_id": "PT-4471", "branch": "Indiranagar" },
  "evidence": {
    "sentiment": "that works perfectly, thank you",
    "disposition": "let's move it to next Tuesday instead"
  },
  "qa": [
    { "key": "verified_identity", "met": true, "evidence": "Can you confirm your date of birth?" },
    { "key": "offered_reminder", "met": false, "evidence": "" }
  ],
  "objections": ["morning slots are hard for me"],
  "score": 88,
  "coaching": [
    { "issue": "Never offered the SMS reminder opt-in", "suggestion": "Offer the reminder before closing the call", "severity": "low" }
  ],
  "hallucinations": [],
  "cx": { "rating": "good", "friction": ["repeated the new date twice"], "highlights": ["reschedule took under 30 seconds"] },
  "topics": ["appointment", "rescheduling"],
  "keywords": ["dental cleaning", "Tuesday", "SMS confirmation"],
  "agentWords": 142,
  "customerWords": 88,
  "agentTurns": 9,
  "customerTurns": 8,
  "model": "openai/gpt-4o-mini",
  "error": null,
  "createdAt": "2026-07-29T09:21:47.115900Z",
  "updatedAt": "2026-07-29T09:21:52.884301Z"
}

TWO NAME COLLISIONS with the enclosing call row — analysis.status is the ANALYSIS job state ("pending" | "done" | "failed"; written by claim_batch/mark_done/mark_failed, post_call_analysis.rs:117,176,211), NOT the call's status; and analysis.disposition is the LLM's outcome label while the row's top-level disposition is the CARRIER disposition (answered/no-answer/busy/failed). A row can exist with status "pending" and every content field null/[]/{}. qa, objections, actionItems, coaching, hallucinations, topics, keywords are jsonb ARRAYS that default to [], never null; customData, evidence, cx are jsonb OBJECTS defaulting to {} (post_call_analysis.rs:337-356 coerces anything non-conforming to the empty form). qa[] is {key, met, evidence}; coaching[] is {issue, suggestion, severity} where severity is low|medium|high and may be null; hallucinations[] is {claim, why}; cx is {rating, friction[], highlights[]} with rating excellent|good|fair|poor or null — these four nested structs have NO rename_all, their fields are single words so they read the same in both conventions. score is the 0-100 LLM-judge quality score (i32|null); sentimentScore is a SEPARATE f32 in -1.0..1.0. agentWords/customerWords/agentTurns/customerTurns are FLAT here — the call.analyzed webhook nests the same four under talkRatio instead. model is "provider/model" (services/post_call_analysis.rs:356). Analysis is per-AGENT opt-in via agents.metadata.postCallAnalysis.enabled and ships OFF, so for most agents nothing was ever produced.

Source: voice_ai_rust/src/db/post_call_analysis.rs:16-58 (struct + #[serde(rename_all="camelCase")]); nested item shapes at voice_ai_rust/src/services/post_call_analysis.rs:84-115 (Coaching/Hallucination/Cx) and 337-356 (normalisation before persist)

GET /api/app-calls (app-key plane, camelCase)

Scope: calls:read (bound agents) | calls:read:org (whole org). +billing:read if includeCost=true

{
  "success": true,
  "data": {
    "calls": [
      {
        "id": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
        "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
        "agentName": "Clinic Reception",
        "status": "ended",
        "callMode": "agent",
        "channel": "telephony",
        "direction": "inbound",
        "startTime": "2026-07-29T09:14:02.331245Z",
        "endTime": "2026-07-29T09:16:11.884012Z",
        "durationSec": 129,
        "fromNumber": "+919845012345",
        "toNumber": "+918031138113",
        "answeredBy": "human",
        "disposition": "answered",
        "wrapupDisposition": null,
        "hasRecording": true,
        "latency": {
          "sttMsAvg": 312,
          "turnHoldMsAvg": 420,
          "llmMsAvg": 688,
          "ttsMsAvg": 241,
          "netRttMsAvg": null,
          "flowMsAvg": null,
          "respMsAvg": 1104,
          "respMsMax": 1980,
          "respSamples": 8,
          "audioGapCount": 0
        },
        "createdAt": "2026-07-29T09:14:02.331245Z",
        "analysis": {
          "sessionId": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
          "orgId": "b1d0a4c7-2e56-4d90-8f3a-6c17e9b25a08",
          "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
          "status": "done",
          "summary": "Caller rescheduled a dermatology appointment from Thursday to Monday morning and confirmed the SMS reminder.",
          "sentiment": "positive",
          "sentimentScore": 0.62,
          "disposition": "appointment_rescheduled",
          "actionItems": ["Send updated confirmation SMS for Mon 10:30"],
          "customData": { "patient_id": "P-40182", "department": "dermatology" },
          "evidence": { "patient_id": "my patient number is four zero one eight two" },
          "qa": [{ "key": "verified_identity", "met": true, "evidence": "Can you confirm your date of birth?" }],
          "objections": ["Thursday slot was too late in the day"],
          "score": 88,
          "coaching": [{ "issue": "Did not offer the earlier 9:15 slot", "suggestion": "Read the two nearest openings before confirming", "severity": "low" }],
          "hallucinations": [],
          "cx": { "rating": "good", "friction": ["hold while checking the calendar"], "highlights": ["confirmed the new time twice"] },
          "topics": ["appointment_rescheduling", "sms_reminder"],
          "keywords": ["dermatology", "monday", "reminder"],
          "agentWords": 214,
          "customerWords": 96,
          "agentTurns": 9,
          "customerTurns": 8,
          "model": "gpt-4.1-mini",
          "error": null,
          "createdAt": "2026-07-29T09:21:44.120388Z",
          "updatedAt": "2026-07-29T09:21:44.120388Z"
        },
        "analysisEnabled": true,
        "cost": {
          "sessionId": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
          "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
          "agentName": "Clinic Reception",
          "callType": "agent_voice",
          "startTime": "2026-07-29T09:14:02.331245Z",
          "llmUsd": "0.001842",
          "sttUsd": "0.000930",
          "ttsUsd": "0.002105",
          "telephonyUsd": "0.006450",
          "platformAiUsd": "0",
          "postCallAnalysisUsd": "0.000410",
          "simulationUsd": "0",
          "embeddingUsd": "0",
          "platformFeeUsd": "0.004500",
          "featureSurchargeUsd": "0",
          "totalChargeUsd": "0.016237",
          "hasEstimates": false,
          "breakdown": {
            "billedMinutes": "2.15",
            "feePercent": "10",
            "feePerMinUsd": "0.002",
            "softphoneFee": false,
            "feeOverridden": false,
            "durationSecs": 129,
            "telephonyBilledSecs": 129,
            "demo": false,
            "featureSurchargeUsd": "0",
            "featureSurcharges": [],
            "feeRule": null
          },
          "ratedAt": "2026-07-29T09:21:00.004881Z"
        }
      }
    ],
    "total": 412,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

DOUBLE-NESTED: rows are at data.calls, not data. analysis, analysisEnabled and cost keys are ONLY present when the matching query flag is set — they are inserted inside if q.include_analysis / if q.include_cost (app_data.rs:589,597), so absent (not null) otherwise. LATENCY IS NESTED: sttMsAvg/llmMsAvg/... live under latency, not flat on the row. analysis: null + analysisEnabled: false means post-call analysis is OFF for that agent and the null is PERMANENT; analysisEnabled: true + null means still pending (app_data.rs:591-595). hasRecording is a boolean only — no recording id or URL is ever exposed on this surface. DELIBERATELY OMITTED from every app call row: the initiating user's identity, metadata, variables (app_data.rs:437-441) — the dashboard's call_to_json (routes/calls.rs:689) has them, this one never does. Money fields are rust_decimal with the default serde feature = JSON STRINGS ("0.016237"), not numbers; the frontend coerces with parseFloat (voice_ai_frontend/src/api/recordings.ts:815). cost.breakdown.events[] is stripped here (app_data.rs:578-580) — per-event detail only from /api/app-billing/charges/:sessionId. includeCost additionally requires billing:read or the whole request 403s (app_data.rs:572).

On failure:

// 403 — neither calls scope granted (routes/app_data.rs:432)
{ "success": false, "error": "requires the calls:read or calls:read:org scope" }

Source: voice_ai_rust/src/routes/app_data.rs:604 (envelope) + app_data.rs:444 app_call_to_json (row) + app_data.rs:589-599 (analysis/analysisEnabled/cost merge)

GET /api/app-calls/:sessionId (app-key plane, camelCase)

Scope: calls:read (must be BOUND to the call's agent) | calls:read:org

{
  "success": true,
  "data": {
    "id": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
    "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
    "agentName": "Clinic Reception",
    "status": "ended",
    "callMode": "agent",
    "channel": "telephony",
    "direction": "inbound",
    "startTime": "2026-07-29T09:14:02.331245Z",
    "endTime": "2026-07-29T09:16:11.884012Z",
    "durationSec": 129,
    "fromNumber": "+919845012345",
    "toNumber": "+918031138113",
    "answeredBy": "human",
    "disposition": "answered",
    "wrapupDisposition": null,
    "hasRecording": true,
    "latency": {
      "sttMsAvg": 312,
      "turnHoldMsAvg": 420,
      "llmMsAvg": 688,
      "ttsMsAvg": 241,
      "netRttMsAvg": null,
      "flowMsAvg": null,
      "respMsAvg": 1104,
      "respMsMax": 1980,
      "respSamples": 8,
      "audioGapCount": 0
    },
    "createdAt": "2026-07-29T09:14:02.331245Z",
    "analysis": {
      "sessionId": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
      "orgId": "5c8b2d41-6e70-4a92-b1f3-2a7d90e4c815",
      "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
      "status": "done",
      "summary": "Caller rescheduled a Tuesday cleaning to the 4th at 11:00.",
      "sentiment": "positive",
      "sentimentScore": 0.62,
      "disposition": "resolved",
      "actionItems": ["Send the caller an SMS confirmation for Aug 4, 11:00"],
      "customData": { "appointment_type": "cleaning", "patient_id": "PT-40912" },
      "evidence": { "sentiment": "Sure — I can do Tuesday the fourth at eleven." },
      "qa": [
        { "key": "verified_identity", "met": true, "evidence": "Can I confirm your date of birth?" },
        { "key": "offered_reminder", "met": false, "evidence": "" }
      ],
      "objections": [],
      "score": 88,
      "coaching": [
        { "issue": "Did not offer an SMS reminder", "suggestion": "Close by offering a reminder text", "severity": "low" }
      ],
      "hallucinations": [],
      "cx": { "rating": "good", "friction": [], "highlights": ["Rebooked in under a minute"] },
      "topics": ["appointment rescheduling", "dental cleaning"],
      "keywords": ["Tuesday", "cleaning", "reschedule"],
      "agentWords": 96,
      "customerWords": 41,
      "agentTurns": 6,
      "customerTurns": 5,
      "model": "claude-sonnet-4-5",
      "error": null,
      "createdAt": "2026-07-29T09:16:20.104553Z",
      "updatedAt": "2026-07-29T09:16:38.772910Z"
    },
    "analysisEnabled": true,
    "transcript": [
      { "role": "assistant", "text": "Thanks for calling Smile Dental, how can I help?", "at": "2026-07-29T09:14:04.102331Z", "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35" },
      { "role": "user", "text": "I need to move my Tuesday cleaning.", "at": "2026-07-29T09:14:09.774210Z", "agentId": null },
      { "role": "assistant", "text": "Sure — I can do Tuesday the fourth at eleven.", "at": "2026-07-29T09:14:15.310884Z", "agentId": "7b0e4c22-1a9f-4d55-8e30-cc61b9a7d248" }
    ],
    "participants": {
      "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35": "Clinic Reception",
      "7b0e4c22-1a9f-4d55-8e30-cc61b9a7d248": "Scheduling Specialist"
    }
  }
}

Single-nested: the call object IS data (no data.call). analysis and analysisEnabled are ALWAYS present here (unconditional, app_data.rs:645-656) — unlike the list route where they are flag-gated. transcript[].agentId is CAMELCASE ONLY ON THIS ROUTE: the shared helper transcript_with_participants emits snake_case agent_id and this handler explicitly renames it (app_data.rs:669-679) — the dashboard proxy twin does NOT, so the same transcript is agent_id there. transcript[].agentId is a STRING uuid read out of message metadata (calls.rs:613-619), and is null on user turns and on any assistant turn written before per-turn attribution. role is only "user" | "assistant" — system turns are filtered out (calls.rs:622). participants is a MAP keyed by agent-uuid string → agent name, and is {} (empty object, not null/array) when no turn carried attribution (calls.rs:640). at is the message created_at, RFC3339.

On failure:

// 404 — not this org's call (app_data.rs:629)
{ "success": false, "error": "call not found" }
// 403 — org owns it but the install isn't bound to its agent, and no :org scope (app_data.rs:639)
{ "success": false, "error": "app is not bound to this call's agent" }

Source: voice_ai_rust/src/routes/app_data.rs:683 (envelope) + app_data.rs:644-681 (analysis + transcript rename + participants); transcript rows built at voice_ai_rust/src/routes/calls.rs:624

GET /orgs/:orgId/apps/:appId/calls (dashboard proxy for app PAGES)

Scope: install must hold calls:read | calls:read:org; caller must be an org member

// GET /orgs/{orgId}/apps/{appId}/calls?limit=50&includeAnalysis=true
{
  "success": true,
  "data": {
    "calls": [
      {
        "id": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
        "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
        "agentName": "Clinic Reception",
        "status": "ended",
        "callMode": "agent",
        "channel": "telephony",
        "direction": "inbound",
        "startTime": "2026-07-29T09:14:02.331245Z",
        "endTime": "2026-07-29T09:16:11.884012Z",
        "durationSec": 129,
        "fromNumber": "+919845012345",
        "toNumber": "+918031138113",
        "answeredBy": "human",
        "disposition": "answered",
        "wrapupDisposition": null,
        "hasRecording": true,
        "latency": { "sttMsAvg": 312, "turnHoldMsAvg": 420, "llmMsAvg": 688, "ttsMsAvg": 241, "netRttMsAvg": null, "flowMsAvg": null, "respMsAvg": 1104, "respMsMax": 1980, "respSamples": 8, "audioGapCount": 0 },
        "createdAt": "2026-07-29T09:14:02.331245Z",
        "analysis": { /* full CallAnalysis, or null */ },
        "analysisEnabled": true
      }
    ]
  }
}

DIFFERS FROM THE APP-KEY TWIN: data carries ONLY calls. There is NO total, NO limit, NO offset, NO hasMore — even though the route accepts limit/offset (apps.rs:2704-2705), so a page cannot tell whether more rows exist except by asking for another page and seeing it come back short. Also no includeCost/cost on this plane at all — AppCallsQuery has no such field (apps.rs:2636-2660). Row shape is otherwise byte-identical to the app-key plane because both call the same builder.

Source: voice_ai_rust/src/routes/apps.rs:2748 (envelope) reusing routes/app_data.rs:444 app_call_to_json for each row

GET /orgs/:orgId/apps/:appId/calls/:sessionId (dashboard proxy for app PAGES)

Scope: install must hold calls:read | calls:read:org; caller must be an org member

{
  "success": true,
  "data": {
    "id": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
    "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
    "agentName": "Clinic Reception",
    "status": "ended",
    "callMode": "agent",
    "channel": "telephony",
    "direction": "inbound",
    "startTime": "2026-07-29T09:14:02.331245Z",
    "endTime": "2026-07-29T09:16:11.884012Z",
    "durationSec": 129,
    "fromNumber": "+919845012345",
    "toNumber": "+918031138113",
    "answeredBy": "human",
    "disposition": "answered",
    "wrapupDisposition": null,
    "hasRecording": true,
    "latency": {
      "sttMsAvg": 312,
      "turnHoldMsAvg": 420,
      "llmMsAvg": 688,
      "ttsMsAvg": 241,
      "netRttMsAvg": null,
      "flowMsAvg": null,
      "respMsAvg": 1104,
      "respMsMax": 1980,
      "respSamples": 8,
      "audioGapCount": 0
    },
    "createdAt": "2026-07-29T09:14:02.331245Z",
    "analysis": {
      "sessionId": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
      "orgId": "6b0d4c11-9e57-4a02-8f3c-2d71b5e9a084",
      "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
      "status": "done",
      "summary": "Caller rescheduled a Tuesday cleaning to Thursday 4pm and confirmed the SMS reminder.",
      "sentiment": "positive",
      "sentimentScore": 0.62,
      "disposition": "appointment_rescheduled",
      "actionItems": ["Send confirmation SMS for Thu 4:00pm"],
      "customData": { "patient_name": "Anita Rao", "new_slot": "2026-08-06T16:00:00+05:30" },
      "evidence": { "new_slot": "Thursday at four in the afternoon works" },
      "qa": [{ "key": "verified_identity", "met": true, "evidence": "Can I have your date of birth?" }],
      "objections": ["Did not want a Monday slot"],
      "score": 86,
      "coaching": [{ "issue": "Did not offer the earlier cancellation slot", "suggestion": "Read the waitlist openings before proposing a new day", "severity": "low" }],
      "hallucinations": [],
      "cx": { "rating": 4, "friction": ["Repeated the phone number twice"], "highlights": ["Confirmed the new time back to the caller"] },
      "topics": ["appointment_rescheduling"],
      "keywords": ["cleaning", "Tuesday", "Thursday", "reminder"],
      "agentWords": 143,
      "customerWords": 61,
      "agentTurns": 7,
      "customerTurns": 6,
      "model": "gpt-4.1-mini",
      "error": null,
      "createdAt": "2026-07-29T09:16:44.512907Z",
      "updatedAt": "2026-07-29T09:16:44.512907Z"
    },
    "analysisEnabled": true,
    "transcript": [
      { "role": "assistant", "text": "Thanks for calling Smile Dental, how can I help?", "at": "2026-07-29T09:14:04.102331Z", "agent_id": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35" },
      { "role": "user", "text": "I need to move my Tuesday cleaning.", "at": "2026-07-29T09:14:09.774210Z", "agent_id": null }
    ],
    "participants": {
      "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35": "Clinic Reception"
    }
  }
}

CASING DIVERGENCE FROM THE APP-KEY TWIN: this route assigns the helper's output straight through (obj["transcript"] = Value::Array(transcript), apps.rs:2822), so transcript rows keep the helper's snake_case agent_id. The app-key route at routes/app_data.rs:669-679 renames it to agentId. Same call, same field, two spellings depending on which plane you read it from — branch on t.agentId ?? t.agent_id. Everything else (top-level camelCase row, always-present analysis/analysisEnabled, participants map) matches the app-key route.

Source: voice_ai_rust/src/routes/apps.rs:2824 (envelope) + apps.rs:2809-2823 (analysis, transcript, participants)

POST /api/app-calls/:sessionId/assist

Scope: calls:transcribe:live

{
  "success": true,
  "data": {
    "armed": true,
    "sessionId": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42"
  }
}

armed is a constant true — it is never false; failure is an HTTP error, not armed:false. Idempotent: re-arming an already-armed live call returns the same body. Manual SOFTPHONE calls only. The transcripts it produces do not come back in this response — they arrive on the call's live stream as call.turn / call.transcript_partial frames with a speaker field (see the live-assist stream row).

On failure:

// 400 — not a softphone call (app_data.rs:767)
{ "success": false, "error": "live assist is only available on manual softphone calls" }
// 409 — not live right now (app_data.rs:779)
{ "success": false, "error": "call is not live" }

Source: voice_ai_rust/src/routes/app_data.rs:792-795 (app-key plane); byte-identical body from the dashboard proxy at voice_ai_rust/src/routes/apps.rs:3106

POST /api/app-calls/:sessionId/stream-ticket

Scope: calls:read (bound) | calls:read:org

{
  "success": true,
  "data": {
    "ticket": "5b81a3c74f6e4d2ab0973e1c8f4d2266",
    "wsUrl": "wss://app.telenow.ai/ws/live-call-stream?ticket=5b81a3c74f6e4d2ab0973e1c8f4d2266"
  }
}

ticket is a 32-char uuid-simple (no dashes), single-use via Redis GETDEL, 30s TTL (app_data.rs:724-728). wsUrl already carries the ticket — connect to it directly; the scheme is derived from x-forwarded-proto (calls.rs:869-880) so it is ws:// only on plain-http local dev.

On failure:

// 409 — call is not live on this node (app_data.rs:721)
{ "success": false, "error": "call is not live" }

Source: voice_ai_rust/src/routes/app_data.rs:735-738 (identical shape from the dashboard twin at voice_ai_rust/src/routes/calls.rs:857)

WS /ws/live-call-stream — frame envelope + orchestrator topics

Scope: calls:read | calls:read:org (enforced when the ticket is minted, not by the socket)

// One JSON TEXT frame per event. Envelope is always {topic, sessionId, data}.
{"topic":"call.transcript_partial","sessionId":"9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42","data":{"corr":"t3:n=greet:g=1","text":"i need to move my tues"}}
{"topic":"call.turn","sessionId":"9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42","data":{"corr":"t3:n=greet:g=1","text":"I need to move my Tuesday cleaning."}}
{"topic":"call.node_entered","sessionId":"9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42","data":{"corr":"t4:n=reschedule:g=2","node_id":"reschedule","node_name":"Reschedule","node_kind":"conversation","node_generation":2,"llm_model":"gpt-4o-mini","tts_provider":"telenow","tts_voice":"aditi","entry_message":"Let me pull up your appointment.","duration_ms":31}}
{"topic":"call.barge_in","sessionId":"9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42","data":{"corr":"t4:n=reschedule:g=2","played_ms":820,"turn_audio_ms":3400}}
{"topic":"call.dtmf","sessionId":"9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42","data":{"corr":"t5:n=reschedule:g=2","digit":"2"}}
{"topic":"call.silence","sessionId":"9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42","data":{"corr":"t6:n=reschedule:g=2","text":"Are you still there?","llm_generated":false}}

THE ENVELOPE IS CAMELCASE BUT EVERY PAYLOAD IS SNAKE_CASE — data is the raw internal trace payload, verbatim. Read frame.data.node_id, frame.data.played_ms, frame.data.llm_generated. Exactly SEVEN topics can ever appear; there are no others (services/live_call_stream.rs:34-44). Topic names are the PUBLIC names, the internal trace types differ (stt.partial→call.transcript_partial, user.turn→call.turn, node.enter→call.node_entered, barge_in→call.barge_in, silence.checkin→call.silence, dtmf→call.dtmf). corr is a diagnostic string "t{turn_seq}:n={node_id}:g={node_generation}" (orchestration.rs:3298-3303) — parse it only if you must. call.node_entered NEVER carries system_prompt: it is removed on the socket path (services/live_call_stream.rs:63-67) even though the debug trace keeps it, and every payload is additionally run through strip_sensitive_in_place. Only single-context/flow VOICE calls emit node_entered. No heartbeat frame exists; the socket closes with code 1000 "call ended" once the call goes non-active (websocket/live_call_stream.rs:112-117).

On failure:

// Auth/liveness failures are WS CLOSE frames, never JSON — code 1008 with a reason
// (websocket/live_call_stream.rs:139-146):
//   1008 "missing ticket" | 1008 "invalid or expired ticket" | 1008 "call is not live"
// Normal end of call: 1000 "call ended".

Source: envelope: voice_ai_rust/src/websocket/live_call_stream.rs:84-88 · topic map: voice_ai_rust/src/services/live_call_stream.rs:34-44 · payloads: voice_ai_rust/src/services/orchestration.rs:11249 (stt.partial), :12004 (user.turn), :22932 (node.enter), :14529 (barge_in), :25673 (dtmf), :16435 (silence.checkin)

WS /ws/live-call-stream — live-assist (softphone) transcript frames

Scope: calls:transcribe:live to arm; calls:read | calls:read:org to subscribe

{"topic":"call.transcript_partial","sessionId":"9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42","data":{"text":"so the renewal quote is","speaker":"member"}}
{"topic":"call.turn","sessionId":"9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42","data":{"text":"So the renewal quote is eighteen thousand.","speaker":"member"}}
{"topic":"call.turn","sessionId":"9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42","data":{"text":"That's higher than last year.","speaker":"remote"}}

SAME TWO TOPICS, DIFFERENT PAYLOAD SHAPE. When the transcript comes from live-assist on a manual softphone call the payload is {text, speaker} — there is NO corr, and speaker ("member" = the human rep's leg, "remote" = the other party) does not exist on the orchestrator's version. Conversely the orchestrator's version has corr and no speaker. Do not assume either field is present: switch on "speaker" in frame.data. Empty/VAD-marker text is skipped, so you never receive a blank text (live_assist.rs:367-370).

Source: voice_ai_rust/src/services/live_assist.rs:372-382 (publish sites) · speaker values from live_assist.rs:83-88 · same envelope as above, websocket/live_call_stream.rs:84-88

Webhook call.analyzed (org webhook endpoints) — NOT the REST analysis shape

Scope: webhook endpoint subscribed to "call.analyzed" or "*"

{
  "event": "call.analyzed",
  "sessionId": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
  "analysis": {
    "summary": "Caller rescheduled a dental cleaning to Tue 4 Aug 11:00.",
    "sentiment": "positive",
    "sentimentScore": 0.62,
    "disposition": "appointment_rescheduled",
    "actionItems": ["Send SMS confirmation for 2026-08-04 11:00"],
    "customData": { "patient_id": "PT-4471" },
    "evidence": { "sentiment": "that works perfectly, thank you" },
    "qa": [{ "key": "verified_identity", "met": true, "evidence": "Can you confirm your date of birth?" }],
    "objections": ["morning slots are hard for me"],
    "score": 88,
    "coaching": [{ "issue": "Never offered the SMS reminder opt-in", "suggestion": "Offer the reminder before closing", "severity": "low" }],
    "hallucinations": [],
    "cx": { "rating": "good", "friction": ["repeated the new date twice"], "highlights": ["reschedule took under 30 seconds"] },
    "topics": ["appointment", "rescheduling"],
    "keywords": ["dental cleaning", "Tuesday", "SMS confirmation"],
    "talkRatio": { "agentWords": 142, "customerWords": 88, "agentTurns": 9, "customerTurns": 8 },
    "model": "openai/gpt-4o-mini"
  }
}

THIS IS NOT THE SAME OBJECT AS THE REST analysis. Two structural differences: (1) the four talk-ratio counters are NESTED under talkRatio here but FLAT (agentWords, customerWords, agentTurns, customerTurns) on the REST/DB shape; (2) the webhook omits sessionId/orgId/agentId from inside analysis (sessionId is hoisted to the top level), and omits status, error, createdAt, updatedAt entirely. model is the same "provider/model" string. Endpoints configured with include_recording / include_transcript get extra top-level recording / transcript keys grafted on per endpoint (voice_ai_rust/src/services/webhook.rs:297-306). A separate, much smaller projection {summary, sentiment, disposition, custom, topics, keywords} is what the app WORKFLOW runtime sees (post_call_analysis.rs:421-428) — note it is custom there, not customData.

Source: voice_ai_rust/src/services/post_call_analysis.rs:387-412 (payload) → enqueued at post_call_analysis.rs:413-414

telenow.calls.arm(sessionId, opts) / telenow.calls.open(sessionId) / telenow.stream.subscribe(...)

Scope: calls:transcribe:live (arm) · calls:read|calls:read:org (open, subscribe)

// telenow.calls.arm(sessionId, { language: 'en-IN', sttModel: 'nova-2' })
{ "armed": true, "sessionId": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42" }

// telenow.calls.open(sessionId) — NAVIGATES the dashboard away, unmounting your page
{ "ok": true }

// telenow.stream.subscribe(sessionId, onEvent) — the RPC resolves to an unsubscribe fn;
// internally the host replies with just:
{ "streamId": "a2c4e6f8-1b3d-4a5c-9e7f-0d2b4c6a8e10" }
// then pushes each socket frame to the iframe as:
{ "source": "telenow-host", "stream": "a2c4e6f8-…", "data": { "topic": "call.turn", "sessionId": "9f1c…", "data": { "corr": "t3:n=greet:g=1", "text": "I need to move my Tuesday cleaning." } } }

• calls.open never touches the server — the bridge synthesises {ok:true} and calls navigate('/calls/:id'), which unmounts the app iframe. stream.subscribe resolves to an UNSUBSCRIBE FUNCTION, not to the streamId — the {streamId} object is internal plumbing (AppPageHost.tsx:330-338).
• The frame handed to your onEvent callback is DOUBLE-NESTED: frame.data is the actual event payload because the host relays the raw socket JSON ({topic, sessionId, data}) as the data of its push message. So the caller's text is at frame.data.text where frame is what onEvent receives. The host holds the WebSocket and the ticket; the iframe never sees either.

Source: arm: voice_ai_rust/src/routes/apps.rs:3106 (bridge passes through, AppPageHost.tsx:948) · open: voice_ai_frontend/src/components/apps/AppPageHost.tsx:738 (hand-built, no server call) · subscribe: AppPageHost.tsx:986 (streamId) and AppPageHost.tsx:979-982 (push envelope)

telenow.calls.get(sessionId) — UI bridge

Scope: calls:read | calls:read:org, AND view-activity role

// resolves to the REST `data` object VERBATIM — camelCase, snake_case transcript
{
  "id": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
  "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
  "agentName": "Clinic Reception",
  "status": "ended",
  "callMode": "agent",
  "channel": "telephony",
  "direction": "inbound",
  "startTime": "2026-07-29T09:14:02.331245Z",
  "endTime": "2026-07-29T09:16:11.884012Z",
  "durationSec": 129,
  "fromNumber": "+919845012345",
  "toNumber": "+918031138113",
  "answeredBy": "human",
  "disposition": "answered",
  "wrapupDisposition": null,
  "hasRecording": true,
  "latency": { "sttMsAvg": 312, "turnHoldMsAvg": 420, "llmMsAvg": 688, "ttsMsAvg": 241, "netRttMsAvg": null, "flowMsAvg": null, "respMsAvg": 1104, "respMsMax": 1980, "respSamples": 8, "audioGapCount": 0 },
  "createdAt": "2026-07-29T09:14:02.331245Z",
  "analysis": { /* full CallAnalysis, or null */ },
  "analysisEnabled": true,
  "transcript": [
    { "role": "assistant", "text": "Thanks for calling Smile Dental.", "at": "2026-07-29T09:14:04.102331Z", "agent_id": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35" }
  ],
  "participants": { "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35": "Clinic Reception" }
}

ASYMMETRIC WITH ITS OWN SIBLING. calls.history() re-projects to snake_case; calls.get() does NOT re-project at all — only the {success,data} envelope is unwrapped. So inside a single app, the same call is agent_id from history() and agentId from get(). Then within THIS object the top level is camelCase but transcript[].agent_id is snake_case, because this route is the dashboard proxy that skips the rename (apps.rs:2822). Three conventions reachable from one app: history rows (snake), get row (camel), get transcript rows (snake).

Source: voice_ai_frontend/src/components/apps/AppPageHost.tsx:794 (data = await getAppCall(...), no re-projection) → voice_ai_frontend/src/api/apps.ts:663 → voice_ai_rust/src/routes/apps.rs:2824

telenow.calls.history(filters, { includeAnalysis }) — UI bridge

Scope: calls:read | calls:read:org, AND the signed-in user must be able to view activity

[
  {
    "id": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
    "agent_id": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
    "agent_name": "Clinic Reception",
    "channel": "telephony",
    "direction": "inbound",
    "from_number": "+919845012345",
    "to_number": "+918031138113",
    "status": "ended",
    "duration_sec": 129,
    "start_time": "2026-07-29T09:14:02.331245Z",
    "end_time": "2026-07-29T09:16:11.884012Z",
    "analysis": {
      "sessionId": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
      "orgId": "c81b4f27-6e0a-4d33-8f52-2a7c9b1d6e04",
      "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
      "status": "done",
      "summary": "Caller rescheduled a dermatology appointment from Thursday to Saturday morning and asked whether the clinic bills their insurer directly.",
      "sentiment": "positive",
      "sentimentScore": 0.62,
      "disposition": "resolved",
      "actionItems": [
        "Send the Saturday 11:00 confirmation SMS",
        "Email the insurance pre-authorisation form"
      ],
      "customData": { "department": "dermatology", "reschedule": true },
      "evidence": {
        "disposition": "great, Saturday at eleven works for me",
        "department": "I need to move my skin appointment"
      },
      "qa": [
        { "key": "verified_identity", "met": true, "evidence": "can I confirm your date of birth?" },
        { "key": "offered_callback", "met": false, "evidence": null }
      ],
      "objections": ["Thursday slot was too early"],
      "score": 84,
      "coaching": [
        { "issue": "Did not offer a callback number", "suggestion": "Close by confirming the best number to reach them on.", "severity": "low" }
      ],
      "hallucinations": [],
      "cx": { "rating": 4, "friction": ["Two attempts to hear the date"], "highlights": ["Reschedule handled in one turn"] },
      "topics": ["appointment_reschedule", "insurance"],
      "keywords": ["dermatology", "Saturday", "pre-authorisation"],
      "agentWords": 142,
      "customerWords": 96,
      "agentTurns": 9,
      "customerTurns": 8,
      "model": "gpt-4o-mini",
      "error": null,
      "createdAt": "2026-07-29T09:16:44.010982Z",
      "updatedAt": "2026-07-29T09:16:51.447203Z"
    },
    "analysis_enabled": true
  },
  {
    "id": "b7e0d413-52c8-4a90-9f6b-1d84c7a2e550",
    "agent_id": "5c9e7a02-13bd-4c77-8e41-6fa03b9d2c18",
    "agent_name": null,
    "channel": "web_call",
    "direction": "web",
    "from_number": null,
    "to_number": null,
    "status": "active",
    "duration_sec": null,
    "start_time": "2026-07-29T09:22:18.664301Z",
    "end_time": null,
    "analysis": null,
    "analysis_enabled": false
  }
]

• THE BRIDGE RE-PROJECTS. Three separate divergences from the REST shape it wraps: (1) the {success,data} envelope AND the calls wrapper are both unwrapped (voice_ai_frontend/src/api/apps.ts:657 does .then(d => d.calls)), so you get a bare array; (2) keys are rewritten to SNAKE_CASE; (3) it is a SUBSET — only the 11 keys above survive. callMode, answeredBy, disposition, wrapupDisposition, hasRecording, latency and createdAt are DROPPED and unreachable through this method. analysis / analysis_enabled appear only when { includeAnalysis: true } is passed.
• The analysis VALUE is spliced in untouched, so its inner keys stay CAMELCASE (actionItems, agentWords) while its wrapper key analysis_enabled is snake_case — one object, both conventions. Filters are validated client-side: anything outside [agentId, callMode, status, from, to, sort, limit, offset] throws rather than being silently ignored (AppPageHost.tsx:755-761). No pagination metadata is available at all.

On failure:

// the bridge rejects the Promise with an Error; the raw postMessage is
{ "source": "telenow-host", "id": "r7", "ok": false, "error": "calls.history: unsupported filter(s) [phone] — this app plane supports agentId, callMode, status, from, to, sort, limit, offset" }

Source: voice_ai_frontend/src/components/apps/AppPageHost.tsx:774-789 (hand-built re-projection) — the underlying REST call is voice_ai_rust/src/routes/apps.rs:2748

Error envelopes across the call surfaces

// Every REST route on both planes (app-key and dashboard proxy):
{ "success": false, "error": "call not found" }                         // 404
{ "success": false, "error": "requires the calls:read or calls:read:org scope" }  // 403
{ "success": false, "error": "app is not bound to this call's agent" }   // 403
{ "success": false, "error": "call is not live" }                       // 409
{ "success": false, "error": "live assist is only available on manual softphone calls" } // 400
{ "success": false, "error": "Something went wrong" }                   // 500, message is always this literal

// Rate limited (extra field):
{ "success": false, "error": "Too many requests, please try again later", "retryAfter": 30 }  // 429

// Expired/invalid JWT (extra machine-readable code):
{ "success": false, "error": "Access token expired", "code": "token_expired" }  // 401

// UI BRIDGE — a different shape entirely, over postMessage:
{ "source": "telenow-host", "id": "r7", "ok": false, "error": "this app didn't request the \"calls:read\" capability" }

TWO DIFFERENT ERROR CONTRACTS. REST is {success: false, error: "<message>"} — note the flag is success, not ok, and there is no data key at all on failure. The UI bridge is {ok: false, error} and the app never sees it directly: the injected rpc() shim rejects the Promise with new Error(d.error) (AppPageHost.tsx:191), so in app code you only get an Error whose .message is that string. A code field appears on 401 (token_expired | token_invalid), on ForbiddenCode 403s, on 502 provider_error, and on the BadRequestCode 400s — which now includes calls.initiate and softphone.dial when the CARRIER refuses for something on the account (exotel_no_credit, exotel_platform_no_credit, exotel_kyc_incomplete, exotel_app_id_missing, exotel_caller_id_invalid, exotel_credentials_rejected, exotel_not_configured, exotel_rejected). Those 400s also carry flat carrier and meta keys next to error. For every OTHER failure on the call/analysis routes there is still no code, so match on HTTP status first and treat code as optional. 500 bodies are always the literal "Something went wrong" with the real cause only in server logs (error.rs:145-148). The live-call WebSocket does not use either envelope — it signals failure with a 1008 close frame carrying a plain-text reason.

Source: voice_ai_rust/src/error.rs:151 (generic {success:false,error}) · error.rs:112-124 (429 + retryAfter) · error.rs:88-92 (401 + code) · error.rs:97-103 (403 + code) · voice_ai_frontend/src/components/apps/AppPageHost.tsx:1042 (bridge {ok:false,error})

Agents & agent config

Creating agents, and the grouped configuration document an improver app reads and patches.

DELETE /api/app-agents/:id

Scope: agents:write

{ "success": true }

NO data key at all — the one route on this surface that breaks the {success, data} convention. Destructuring const { data } = res yields undefined, not {}.

On failure:

403 when the agent exists but this app did not create it (app_agents.rs:200-202):
{ "success": false, "error": "agent was not created by this app" }
404 for missing/cross-org: { "success": false, "error": "agent not found" }

Source: voice_ai_rust/src/routes/app_agents.rs:204

GET /api/app-agents (list agents THIS app created)

Scope: agents:read

{
  "success": true,
  "data": {
    "agents": [
      { "id": "7c1f0b8e-3a24-4d51-9f6e-2b8c0d1a4e77", "name": "Front Desk", "kind": "single" },
      { "id": "b41d9a02-5e67-4c8a-8f13-9d0e6a2c5b90", "name": "Collections", "kind": "flow" }
    ]
  }
}

DOUBLE-NESTED: data.agents, not data. Key is id (create returns agentId for the same value). Only agents stamped metadata.createdByApp == <this app> are returned (created_by, app_agents.rs:92-99) — an agent the org built and merely CONNECTED to the app does NOT appear here even though /config, /public and /eval all work on it. Hard-capped at 500 rows with no paging and no total (list_for_org(org, 500, 0, None) at :174-176).

Source: voice_ai_rust/src/routes/app_agents.rs:177-182

GET /api/app-agents/:id/config (the full agent-config document)

Scope: agents:config:read

{
  "success": true,
  "data": {
    "agentId": "7c1f0b8e-3a24-4d51-9f6e-2b8c0d1a4e77",
    "name": "Front Desk",
    "description": "Books and reschedules appointments",
    "kind": "flow",
    "updatedAt": "2026-07-29T09:14:22.481930Z",
    "prompt": { "systemPrompt": "You are the front desk for Acme Dental. Be brief." },
    "model": {
      "provider": "openai",
      "model": "gpt-4o-mini",
      "temperature": 0.7,
      "maxTokens": 300,
      "config": { "provider": "openai", "model": "gpt-4o-mini", "temperature": 0.7, "maxTokens": 300 }
    },
    "voice": {
      "provider": "elevenlabs",
      "voice": "21m00Tcm4TlvDq8ikWAM",
      "config": { "provider": "elevenlabs", "voice": "21m00Tcm4TlvDq8ikWAM", "speed": 1.0 }
    },
    "stt": {
      "provider": "deepgram",
      "config": { "provider": "deepgram", "language": "en-IN", "punctuation": true }
    },
    "behavior": {
      "memoryType": "ephemeral",
      "maxDuration": 600,
      "contextMode": "window",
      "silenceHangupSecs": 30,
      "bargeInSensitivity": 0.5,
      "debugTrace": true
    },
    "telephony": {
      "provider": "twilio",
      "config": {
        "phoneNumber": "+918031138113",
        "firstResponse": "agent",
        "agentMsg": "Thanks for calling Acme Dental.",
        "recording": true
      }
    },
    "flow": {
      "schema": 1,
      "startNodeId": "greet",
      "nodes": [
        {
          "id": "greet",
          "kind": "conversation",
          "name": "Greeting",
          "position": { "x": 0, "y": 0 },
          "prompt": "Greet the caller and find out what they need.",
          "promptMode": "append",
          "toolCount": 0,
          "precallLookupCount": 0
        },
        {
          "id": "book",
          "kind": "tool",
          "name": "Book slot",
          "config": {},
          "toolCount": 2,
          "precallLookupCount": 1
        }
      ],
      "edges": [
        { "id": "e1", "source": "greet", "target": "book", "condition": { "kind": "ai", "describe": "caller wants to book" } }
      ]
    },
    "analysis": { "enabled": false, "customFields": [], "qaCriteria": [] },
    "tools": [
      { "name": "book_appointment", "description": "Book a slot in the clinic calendar", "kind": "http" }
    ],
    "realtimeEngine": null
  }
}

• camelCase throughout. Every one of the 12 top-level keys is ALWAYS present — none are omitted.
• flow is null for a single-context agent (agent_config.rs:282-292); everything else is identical, so prompt.systemPrompt works without branching on kind.
• voice.config / stt.config / telephony.config are null (NOT {}) when the underlying column is NULL — public_blob returns Value::Null for None (:192-196). behavior is the session_config object itself (never null, may be {}), and it is FLAT — there is no behavior.config wrapper, unlike every other provider group.
• model.temperature / model.maxTokens are ALWAYS-present keys read out of llm_config; they are null when the blob lacks them (llm.get(...) → None → null, :304-305). They are also DUPLICATED inside model.config, which is the raw llm_config blob (so config.provider/config.model repeat the flat fields too).
• Secrets are removed by KEY NAME from every blob (strip_sensitive_in_place, utils/secrets.rs:118-153,213-228): apiKey, token, authToken, accountSid, clientSecret, authorization, x-api-key, password, privateKey, accessKeyId… So a Twilio telephony.config shows phoneNumber/firstResponse but NEVER accountSid/authToken, and a node override never shows model.extra.apiKey.
• Flow nodes are RE-PROJECTED (public_node, :223-249): tools and precallLookups arrays are DELETED and replaced by integer toolCount / precallLookupCount; the whole node is then secret-stripped, so a transfer node keeps config but with credentials removed. Everything else on the node passes through as stored.
• tools is agent-level and reduced to {name, description, kind} only (public_tools, :254-271); kind falls back to "custom" when absent, name/description fall back to "" (never null).
• analysis.enabled is the NEWER group — it defaults to FALSE, and its own doc comment (:323-328) says this is why an app reading calls with includeAnalysis=true sees analysis: null on every row. customFields/qaCriteria default to [] when metadata.postCallAnalysis is absent (:331-338). Truthiness matches the claim query exactly, including legacy strings: "true"/"yes" → true, a JSON NUMBER (1) → FALSE (pca_enabled, :350-354 + tests :1033-1049).
• analysis.minDurationSec / analysis.minCustomerTurns are the minimum-substance thresholds — the second reason analysis can be null on a call whose agent has enabled: true. A finished call under the threshold is never CLAIMED, so it has no row at all (not a failed one), costs nothing, and is absent from every rollup. Both are RESOLVED on read, never echoed: an absent or undecodable stored value is reported as the platform default (20 seconds / 2 customer replies), because that is the number the claim gate will actually apply — an app told null would mis-diagnose its own missing rows. Which one applies depends on channel: whatsapp/instagram/web_chat/chat are gated on customer TURNS, everything else on SECONDS (a chat's duration is reply latency, not how much was said). Both are WRITABLE with agents:config:write:analysis, unlike analysis.model; values are clamped to 3600 / 100 and decoded exactly as the SQL gate decodes them (a number, or a ≤6-digit string; a bool, {}, [], "soon" and "-5" all fall back to the default). The gate reads them from the call's bind-time snapshot, so editing a threshold never re-gates calls that already ran.
• realtimeEngine is a bare provider STRING (or null) pulled from s2s_config.provider (:342-343) — not the s2s blob.
• updatedAt is RFC-3339 with sub-second precision; echo it as ifUnmodifiedSince on the PATCH.
• FE TYPE DRIFT: the TypeScript AppAgentConfig at voice_ai_frontend/src/api/apps.ts:583-599 does NOT declare analysis, and AppAgentConfigPatch (:604-620) omits it from the Pick — so the runtime serves a group the types deny. The bridge derives groups from Object.keys() at runtime, so { analysis: {...} } works; only the type is wrong.

Source: voice_ai_rust/src/services/agent_config.rs:279-345 (read_config); returned at voice_ai_rust/src/routes/app_agents.rs:361

GET /api/app-agents/:id/public and PUT /api/app-agents/:id/public

Scope: GET agents:read · PUT agents:write (plus the app INSTALLER must be an org owner/admin)

{
  "success": true,
  "data": {
    "isPublic": false,
    "slug": "a3f19c0d4b72",
    "publicUrl": "https://app.telenow.ai/p/a3f19c0d4b72",
    "embedSnippet": "<script src=\"https://api.telenow.ai/widget.js\" data-slug=\"a3f19c0d4b72\"></script>"
  }
}

GET and PUT return the IDENTICAL body — PUT is not a no-content route. slug is 12 lowercase hex chars (gen_slug, services/publish.rs:355-357) and is materialised LAZILY by get_or_create, so the URL is present and stable even while isPublic is false (the widget just 404s). publicUrl uses FRONTEND_BASE_URL, embedSnippet uses PUBLIC_BASE_URL — two different hosts, trailing slash trimmed. PUT body is {"enabled": true} (SetPublicBody, :447-453). Only is_public changes; branding/access code/lead capture are read back and preserved (set_agent_public, :464-487).

Source: voice_ai_rust/src/routes/app_agents.rs:284-296 (public_link_json), returned at :444 (GET) and :505 (PUT)

GET /api/orgs/:orgId/apps/:appId/agent-teams

Scope: — (org member; catalog fallback when not installed)

{
  "success": true,
  "data": {
    "teams": [
      {
        "id": "front-desk-team",
        "name": "Front Desk Team",
        "description": "Reception plus billing",
        "memberCount": 2,
        "members": [
          { "ref": "receptionist", "name": "Receptionist", "kind": "flow" },
          { "ref": "billing", "name": "billing", "kind": "single" }
        ]
      }
    ]
  }
}

Nested at data.teams. Members here use ref + name + kind — there is no agentId yet (nothing has been built). Both name fields fall back to their id/ref (:897, :902). memberCount is just members.len(), so it is always redundant with the array.

Source: voice_ai_rust/src/routes/apps.rs:892-908

GET /api/orgs/:orgId/apps/:appId/agent-templates (what an app ships)

Scope: — (org member; falls back to the CATALOG manifest when not installed)

{
  "success": true,
  "data": {
    "templates": [
      { "id": "front-desk", "name": "Front Desk", "description": "Answers and books", "kind": "flow" },
      { "id": "after-hours", "name": "after-hours", "description": null, "kind": "single" }
    ]
  }
}