Inbound AI Calls

Reviewed introductory answers can be prepared before calls. Each language has exact approved wording tied to the current organization, Brain generation, source conditions, references and speech style. The phone AI receives only intent, exclusions, language and an opaque card ID. Its optional business_answer.prepared_voice_card_id selection must fit the entire current question and choose one topic without source projection. Follow-ups, staff-dependent requests, actions, prices, availability, eligibility, comparisons and unclear questions retain the live answer path.

The server verifies the selection against the catalog delivered for that call and the current durable approval. Valid prepared answers use the shared answer trace and speech process without live composition or review requests. Their prepared_voice_exact_wording_v1 review origin means approval of exact wording before the call, not a new review of the current conversation. Full source and approval checks run again before speech. An invalid or stale card falls back to live composition and review; exact delivery confirmation and no-replay rules remain. Code availability does not mean cards are prepared or faster live speech is proven. Actual preparation needs a fresh finite paid allowance and scoped generation activation approval.

Inbound AI Calls answers a configured organization number using that organization’s reviewed Business Brain. The demonstration page is /app/inbound-calls. It displays a telephone number only after provider preparation, worker readiness, and live verification have been recorded.

Routine calls can continue without a signed-in operator. The desk separates live requests from saved follow-ups and shows each request’s question, reason, wait, priority, and current owner. An authorized operator can claim one call, hand it to another operator, or release it. Availability is an explicit short-lived signal; merely viewing the desk does not say that someone is available. A required staff decision pauses factual answer requests on that call until an operator explicitly selects the request, confirms the instruction contains the decision, and the provider accepts it. Other calls continue. The assistant may acknowledge the caller or collect permitted details while waiting. If no one replies within the configured wait, it offers to save a request after confirming contact details; saving a request is not a promise that staff will reply.

The full private call record combines conversation, answer lookups, sources, staff instructions, delivery states, and follow-up work. Staff may flag a specific issue into the existing Assistant Training review queue. A flag stays pending until an authorized reviewer dismisses it or approves a correction or coaching. Private call guidance is not reusable knowledge. Call-source text retests use the inbound answer path and are labeled as text-only; they do not prove spoken audio or call timing. Deleting a call also removes its raw Training evidence, while deliberately approved reusable learning remains subject to the existing Training rules. These are signed-in app capabilities, not public Tool Connector operations.

The staff desk is /app/organizations/{organization}/inbound-calls. Organization owners and administrators can grant a member Calls-only access to handle calls and flag issues. Only owners and administrators can change settings or erase call history. These routes use the signed-in browser session. Writes require CSRF protection. They are private application routes, not a public dialing API or MCP capability.

Private guidance has two explicit desk modes. Guide the conversation is the desk default. At a safe speech pause, the provider receives the staff text as private JSON inside a bounded system instruction and may make one short, natural conversational move in the caller’s language. It must not reveal the note, treat it as a business answer, bypass the required business_answer and reviewed-answer path, claim a callback, human, availability, or action, or bypass confirmed-contact and saved-receipt rules. Provider acceptance means only that it accepted the control request. It does not prove that a caller heard or followed the resulting speech.

Add answer information keeps the earlier factual-context behavior. The provider receives only a nontriggering private-context notice, then the server may create a reviewed Business Brain answer using accepted staff input as private evidence. Omitted mode remains this legacy context mode for existing direct service callers. Staff must choose the relevant request; decision requests also require an explicit declaration. Provider acceptance records staff input, not a spoken answer or confirmed outcome. Conversation guidance never creates an answer lookup, resolves help, or becomes staff factual evidence. A newer direction cancels an older undelivered direction; an active caller or assistant speech turn leaves conversation guidance pending until a safe pause. Neither mode adds a public API, MCP capability, or public OpenAPI operation.

Caller language and staff display language are separate. The supported configuration is English and Spain Spanish. Transcripts preserve the original wording and show translation states. Dictation creates a private draft for review; it never connects the staff microphone to the caller.

Routine speech should be brief and use the organization’s team voice, such as “we” and “our.” The managed assistant does not repeat its introduction or volunteer explanations of its AI identity after the configured opening. It still answers truthfully when asked whether it is AI and retains required disclosures. Configured greetings and recording notices are rendered exactly; changing spoken copy does not change retention or recording settings. Existing provider profiles need a scoped refresh to receive new instructions.

The live answer composer, independent reviewer, and routine phone replies share a respectful plain-language contract at no more than a sixth-grade reading level. Introductory questions receive a short useful overview. Source authority labels and review categories stay private. A qualification that materially changes the answer must still be explained in everyday words; simpler speech does not permit unsupported service promises or removal of central conditions. Prompt checks establish the contract, not actual caller-perceived quality.

Private recording playback accepts provider-verified Vapi redirects to the observed R2 host shape hipaa-recordings.{32-lowercase-hex-account-id}.r2.cloudflarestorage.com, alongside the existing approved storage families. Other R2 host shapes are rejected. HTTPS, public DNS validation and pinning, redirect rejection, separate credential-free storage requests, MIME checks, and the 32 MiB cap remain required. A call’s recording-enabled snapshot permits playback; an unused local recording_state default alone does not establish whether provider audio exists.

Before saving a follow-up, the assistant reads phone numbers digit by digit and email addresses character by character, including “at” and “dot” in the caller’s language. The caller must confirm or correct the contact details. A saved follow-up is private staff work in the organization call desk. Saving a follow-up does not send an owner or caller email notification, and a saved receipt must not be described as an email sent or a callback booked. Separately, admitting a telephone call (including the public phone demo) sends a minimal internal activity alert to the configured Bombyx operator. It includes only type, time and a system-admin link that opens the exact organization’s call desk. Browser demo starts use the same minimal alert contract described in Guided Calling, without saving conversations.

Every managed voice tool supplies the caller’s current language as en or es, including human-help, follow-up, and cancellation requests. This structured decision updates the current caller turn and future status speech. It does not change the staff display language. The provider subscription uses plain transcript events; partial events are discarded. Actual final transcript events take precedence over terminal conversation records, which can include text added to model context without being spoken. A fallback conversation record is labeled as unconfirmed speech.

An accepted speech command is kept separate from the conversation until actual transcript evidence confirms speech. The desk retains delivery status in its details. Call recaps receive bounded staff-guidance delivery states so that a later staff-assisted answer is understood in context; private staff instructions are excluded from recap generation.

The dedicated Vapi callback is POST /app/webhooks/vapi/inbound-voice. It uses a separate bearer credential and validates the provider account, number, call type, and assistant binding. The number uses dynamic assistant selection. Call setup only resolves prepared local state; reviewed Brain answers run on a separate queue. After a question receipt, the managed assistant gives one brief, natural acknowledgement that varies within the call. It must not describe internal reviews or queues, or imply that a person is reviewing the question. Duplicate tool requests and staff commands use durable identities. An uncertain delivery is not automatically repeated.

If a provider supplies a nonempty, valid-shaped AI-selected topic list but omits only prepared_navigation_id, the server copies the identity from that call’s immutable prepared snapshot. It does not choose topics or facts. Explicit invalid identities retain the existing selector fallback. The answer path still rebuilds and checks the packet against the live organization, chatbot, settings, generation, fingerprint and source eligibility before accepting the selection. This avoids a redundant semantic selection request when the sole defect is the omitted opaque ID.

Provider readiness audits retain only safe failure categories and codes. Temporary connection, rate-limit, timeout and server failures leave readiness disabled and become eligible for one maintenance recheck after thirty seconds. Identity, configuration and other failures keep the ten-minute audit interval. A complete successful audit clears the failure markers; an earlier recheck never permits stale provider settings.

Provider control and listening URLs remain on the server. Listening and recording playback use authenticated same-origin routes. End remains pending until provider confirmation. Closing the browser does not end the call. An organization can configure only a validated transfer destination; transfer receipts distinguish acceptance from completion.

The managed provider profile uses a 90-second silence timeout, capped by the organization’s maximum call duration. This allows time to review private guidance and finish a reviewed answer. The total call duration remains bounded. Provider readiness checks detect changes to either timeout.

Waiting notices use short, varied English or Spanish wording without extra AI requests. First updates use at most nine words and the wait-or-help choice uses at most ten, reducing the time an update can occupy the speech boundary. The interruption reminder appears only in the first notice for a lookup. Before speaking a reviewed fact, the service validates that fact’s current source and reviewed capsule; an older chunk retained as provenance does not replace the fact’s revision. If current-question evidence is no longer eligible, the caller receives a lookup-failure notice with help or follow-up options. Replaced questions remain silent.

The default lookup deadline is 30 seconds. Evidence preparation and answer generation share a 16-second budget, with six seconds reserved for delivery. Large Brains first use a structured AI decision over the complete topic index, bounded by six seconds and the remaining generation time. The mandatory reviewer receives every reviewed claim in the selected topics and their explicit related topics, along with global conflicts and limits. That same AI decision can optionally choose declared source groups for a smaller composer input when the question is clearly source-focused. Exact current source identities bind the groups. Invalid, missing or inapplicable selections fall back to the full topic packet. The smaller composer packet is explicitly incomplete topic coverage; the full reviewer can recover omitted qualifications and references before speech. Staff facts, resource links and global constraints remain available. Compact claim rows retain exact positional field mappings, including source attribution and explicit or inferred status. Voice-specific instructions favor brief spoken answers while retaining qualifications central to the question; website formatting rules remain separate. Small packets go directly to composition and review. No text-matching rules or claim-count limits select the evidence.

Waiting updates are limited to two per question, starting near ten seconds with at least eight seconds between them, and wait for a speech boundary. If the current question has entered final review, an identity-bound temporary hint can defer its first notice by at most two seconds. Missing, invalid or stale hints preserve normal notices. Ready answers, failures, deadlines and ended calls take priority over this grace period. A caller can ask for reassurance without restarting the question, or choose human help to replace the pending answer.

Telephone topic selection, composition and review each use one bounded provider request. Cross-provider fallback, reviewer hedging and invalid-output retries are disabled for this workflow. Timeouts are capped by the remaining generation window after a short transport margin; a stage without one second of usable time is refused before dispatch. Failure stays explicit and offers help rather than an unreviewed business answer.

Provider acceptance is not proof of audio. An uncertain speech request is never replayed. If no final transcript confirms it within eight seconds, the desk reports unconfirmed delivery. Normally the caller gets one neutral offer of team help, with wording that varies across questions in the same call. An exact current-answer force-say playback-start diagnostic can suppress that optional interruption when no interruption is known. It does not confirm that the answer finished or was heard. Recovery reads the persisted diagnostic under the call and lookup locks. A valid delayed event can cancel a pending recovery; dispatch checks again before claiming speech. Speech already handed to the provider is never revoked or replayed. Missing, stale, mismatched or interrupted diagnostics retain normal recovery, and the caller can still ask for help. Actual final assistant transcripts can confirm the answer later. Generic speech-start timing and conversation snapshots remain insufficient confirmation. These are private desk diagnostics; no public API operation or schema changes.

After a reviewed answer is durably ready, its answer job immediately creates and dispatches the existing speech command, without waiting for a maintenance pass. The normal queued command and maintenance recovery remain available if a caller or assistant is speaking. Duplicate jobs share the same durable command and cannot replay an accepted or uncertain request. Current call, question, language, guidance, deadline and evidence checks still run before speech. This removes a polling boundary; it does not guarantee a particular answer latency.

Reviewed answers request speech before updating the provider’s conversation history. The server records the speech receipt promptly, then sends one nontriggering history update only while the call, question, language, guidance, deadline and evidence remain current. A withdrawn source or caller interruption skips that update. A failed history update never downgrades accepted speech or causes answer replay. Private timing details separate speech control from history control.

For telephone review, complete scoped evidence and its available reference keys precede the changing question and draft in the stable review catalog. Selected-topic review details stay with the current request. This preserves every supplied claim and reference while allowing the provider prompt cache to reuse the prepared prefix; it does not cache final answers or prove a latency gain.

Prepared evidence is cached in a versioned plain-array envelope compatible with the database cache’s disabled PHP-class unserialization. Each lookup still verifies the current organization, audience, generation and dependency fingerprint. Final assistant transcript fragments confirm speech only when their contiguous exact word sequence matches the current request, after its provider timestamp, with no caller, interruption or context boundary. Conversation snapshots cannot assemble proof.

When a managed inbound assistant is prepared, it may receive a bounded navigation packet for the then-current Brain. Its business_answer tool call can return the packet ID, selected topic IDs, and optional source-group IDs. Laravel stores that optional selection with the call lookup, rebuilds the current full context, and accepts it only when every call, organization, chatbot, settings, generation, dependency, and ID check still matches. A stale or malformed selection uses the normal structured topic-selection step. The packet never contains a prewritten answer, and source groups only narrow composer input; the reviewer still receives the full selected and related evidence.

An approved prepared voice card may list up to twelve exclusions, including the required introductory-answer boundaries. The stored card, current evidence, approval certificate and exact packet advertisement must still match before Laravel can use its reviewed wording. Existing approved cards remain eligible when those checks match; they do not need preparation again solely because they use this supported exclusion count.

Omitting the optional composer_source_group_keys field keeps the complete selected evidence and does not invalidate an otherwise current navigation selection. An explicitly null or malformed field uses the normal selector fallback. An empty list also keeps complete selected evidence. Neither omission nor an empty list removes the full selected and related reviewer context.

A newly compiled Brain can optionally contain independently approved finer review scopes. This scope phase is off by default and requires an explicit list of current topic IDs. The added phase uses at most one proposal request and one separate review request for each requested topic, without retries, fallback or hedging. Existing Brain compilation requests remain separate costs. Both proposal and independent review receive the complete topic evidence, transitive related evidence, source-only caveats and unknowns, global constraints and current answer policy. Approved scopes bind their intent, exact dependencies, required qualifier scopes and source-only qualifiers to that immutable generation. Invalid or rejected compilation keeps full-topic review.

When current approved scopes are present, the navigation tool can optionally send selected_review_scope_keys as an object mapping each selected topic ID to a nonempty list of its declared scope keys. Every selected topic must be covered. Missing, empty, malformed, unknown, foreign or stale scope selections keep full selected-topic evidence. Laravel independently checks persisted approval and current semantic content and expands required qualifier scopes. Version 1 scopes retain complete transitive related-topic evidence. Version 2 scopes explicitly certify exact related fact IDs and chunk keys for each intent; empty related lists are permitted only under that separate semantic approval. Their reference eligibility is limited to the complete explicit related closure, and changes to that full original context or policy invalidate approval. The same closed evidence and applicable source-only qualifiers feed both composition and mandatory review. This is complete coverage for the certified intent, not proof of whole-topic or organization-wide coverage. Scope selection cannot grant approval or use blueprint anchor references as complete evidence. Older Brains and prepared profiles keep their existing packet and tool contract. These optional private provider arguments add no public Tool Connectors OpenAPI operation.

New preparations can render that navigation as transparent inbound_voice_navigation_rows_v1 field tables. Each table declares its field names once, keeps literal values in aligned rows, and records omitted columns separately from null values. Global conflicts, limitations, replacements and coverage remain unchanged. The encrypted prepared snapshot records the prompt transport version, so older plain-navigation assistants retain their original expected audit format. This changes prompt transport only; packet identity, runtime freshness checks, tool arguments and reviewer scope are unchanged. Smaller input does not establish lower model cost or faster audio.

The existing maintenance loop warms at most one eligible prepared chatbot per pass without provider or AI requests. Exact environment, organization and prepared-setting revision checks gate the work. Per-chatbot locks and 15/60-second failed/successful cooldowns bound rebuilds; the builder’s freshness-bound cache expiry is unchanged. First and second waiting notices rotate separately across questions, including calls where each answer finishes before a second notice. An explicit request for a person invokes staff help before contact collection; only a saved follow-up requires confirmed contact details.

The managed assistant uses the whole conversation to recognize when a caller wants to get started or leave contact details. After the caller agrees, it asks for a phone number or email rather than repeating service information or asking for agreement again. Contact collection does not require a knowledge lookup. It reads each phone digit or email character, obtains explicit confirmation, and invokes save_followup immediately with the caller’s current request. It may say the details were saved only after a successful receipt. A request to leave details alone does not establish a request for a person on the live call. Saved requests remain private call-desk records, without a promise of a reply or callback.

Inbound text AI requests use the existing organization-owned run spending limit before provider dispatch. Each supported attempt reserves a conservative estimated cost using its resolved provider/model, dated saved rate, bounded text input and output allowance. A retry or fallback needs its own reservation; inbound requests cannot use the hedged transport. Unknown pricing, unsupported input, invalid run context or insufficient budget stops the request before transport. A timeout, missing usage or missing persisted receipt retains its reservation. Complete exact receipts settle actual recorded costs without clearing other held attempts. Summaries and text translations use private tracked runs with bounded output and no retry or fallback. Translation failure leaves the original transcript available.

This is an estimated per-run app text AI guard. It is not a per-call or monthly invoice cap and does not cover Vapi voice processing, carrier/number charges, recording/storage, microphone dictation’s separate audio transcription endpoint, or Codex implementation work. Saved prices and provider billing may differ. Ready answers make no live app model request; typed staff direction does not add a composition request. These private changes do not add public OpenAPI operations or change customer billing.

Recording defaults to off. Enabling it requires an approved policy and caller notice. Private text is encrypted in application storage. The configured retention period removes private call content and queues deletion of provider artifacts. Deleting a call requires that it has ended; a retained tombstone prevents late events from restoring its content. Pending provider deletion is reported as pending.

For the current prelaunch Bombyx Labs demo, the explicit private_recording_without_notice_bindings configuration permits previously approved recording without a spoken notice for organization 17, number 1 only, including its public demo card. The card states that calls are recorded before the phone action. Approval remains required in settings; other numbers and organizations retain the normal spoken-notice gate. Nick deferred a spoken notice until formal launch. Reassess this exact exception before that launch. Recording remains encrypted/private and subject to the existing retention and authorized-playback controls.

An accepted contextual answer with current provider speech activity and a later actual assistant transcript does not need an automatic team-help offer merely because transcript spelling differs. This transport observation only suppresses that optional interruption. It does not confirm the answer text, change delivery_unconfirmed, replay the answer, or replace the exact delivery check. Unknown provider acceptance, stale context, interruption, and missing actual speech retain normal recovery. Callers can still request team help themselves.

The new webhook and desk are cataloged as private integration surfaces. They do not add operations or capabilities to the public Tool Connectors OpenAPI contract.