Concepts
The core architectural resources and terminology of the Orbitali platform.
Understanding the following primary resources and behaviors will help you design and build voice experiences with Orbitali.
Agents
An Agent is the central voice AI configuration. It defines:
- The conversational persona (the system prompt)
- The language and voice used during conversations
- The system and developer tools available to the model during the call
- The linked carrier phone numbers that route to it
Agent types and prompt modes
Agents have one of three integration types: static, HTTP, or webhook. Static agents use saved instructions without custom HTTP/webhook tools. HTTP agents call each tool’s configured endpoint. Webhook agents send tool events to a Server URL and can optionally fetch per-call instructions. The type cannot be changed after creation.
All three types support static prompts; only webhook agents support dynamic prompts. Compare agent types before creating one. The AI Builder is a way to create HTTP agents, not another type.
Phone Numbers & BYO Carrier
Orbitali uses a Bring Your Own Carrier (BYOC) model. Rather than purchasing numbers from Orbitali, developers lease numbers in their personal carrier accounts (Twilio or Telnyx).
By setting the carrier's inbound webhook URL to point to Orbitali's ingress nodes, calls are routed to Orbitali. The platform maps the incoming call destination to the assigned agent ID and starts the voice session.
Prompts (Static vs. Dynamic)
Static Prompts
Static prompts are stored directly in the Orbitali database. For UX authoring convenience, static prompts are split into two fields:
- Identity: Defines who the agent is (e.g., persona, tone, gender, name).
- Instructions: Defines what the agent does (e.g., business hours, triage rules, appointment policies).
At call startup, Orbitali combines these into a single system instruction payload:
{identity}
{instructions}
Dynamic Prompts
Webhook agents can use Dynamic Prompts when they need customer-specific instructions at session startup. HTTP agents can instead retrieve live data through tools during a conversation.
Before answering the phone call, the Go agent sends an agent:assistant-request HTTP POST webhook to your Server URL with the caller's metadata. Your server fetches customer records and returns a customized prompt (which overrides the agent's identity and instructions) and an optional custom greeting.
Tools
System Tools
System tools are built-in actions handled natively by the Go agent. They do not trigger webhook calls and add zero developer latency:
hang_up: Always exposed. Allows the agent to end the telephony leg gracefully when the call finishes.transfer_call: Exposed if the agent has atransfer_destination_e164number configured. Executes a carrier-level transfer to hand the call off to a human agent.search_knowledge: Automatically exposed if the agent has active documents in its Knowledge Base. Connects the model to local RAG retrieval.
Developer Tools
Custom tools are functions with JSON Schema parameters. On HTTP agents, each tool calls its own endpoint with its configured method and headers. On webhook agents, tool calls arrive as agent:tool-call events at the agent’s Server URL. The result is returned to the model to continue the conversation. Static agents do not support these custom tools. Built-in knowledge retrieval and connected MCP tools are separate capabilities.
See Designing Tools for contracts and the API reference for configuration.
Knowledge Base (RAG)
The Knowledge Base is a native Retrieval-Augmented Generation (RAG) system. You can upload company documents (Markdown or PDF) directly.
- Processing: Orbitali extracts the document text and indexes it for semantic search.
- Retrieval: During calls, the agent uses the built-in
search_knowledgetool to find relevant passages in its knowledge base and use them to answer the caller.
Realtime Web Sessions
For browser-based calling, you can create ephemeral WebSocket voice sessions:
- Security: Your backend makes an authorized POST request to
/public/v1/agents/{id}/realtime-sessionsand receives an ephemeral token that expires in 60 seconds. This allows browser calling without exposing your primary API keys. - WebSocket Streaming: The client browser establishes a direct WebSocket connection to the voice runtime. The client streams raw mono PCM16 16 kHz input audio to the server and receives back synthesized PCM16 24 kHz output audio to play.
Call lifecycle notifications
Organization webhooks send call.started, call.ended, and call.summary events for every agent type. Configure them in Settings → Webhooks to automate work around calls. They are asynchronous notifications; agent Server URL webhooks supply prompt and tool responses during conversations. The two protocols use different envelopes, secrets, and signature formats.
Calls & Transcripts
A Call represents an active or completed voice interaction.
- Status Lifecycle: Starts as
initiated, changes toansweredandin_progressonce connected, and terminates ascompleted,failed(e.g., model or carrier failure), ormissed. - Transcripts: Speech transcripts are stored in the database as a sequence of dialogue turns (with a role of
callerorassistant). - Observability: Every custom tool invocation is logged with its full request headers, request body, response status, response body, latency, and errors for auditability.