Agent call flow
A high-level description of how Ocular handles a phone call with an AI voice agent, both when the call arrives from the public network and when Ocular places it. It is the background for the next two pages: how a carrier or partner hands calls to us over SIP, and how Ocular can send a call back out to a PSTN destination.
Components
| Component | Role |
|---|---|
| Carrier / partner | Connects the public telephone network (PSTN) to Ocular over SIP. Today: a bidirectional trunk for Chile and an inbound-only trunk for the United States. |
| SIP edge (FreeSWITCH) | Receives and originates SIP calls, negotiates codecs and RTP/SRTP, and hands signaling and audio to the engine. One SIP profile per carrier. |
| Dialer engine | Services that decide when and whom to call, enforce the legal rules per country, bring the call to the agent and record what happened. |
| Orchestrator | Adapter between the engine and the conversational voice-agent provider. Reserves sessions, bridges audio and runs the agent's tools. Switching providers touches neither the engine nor the SIP edge. |
| Ocular OS | The business platform: projects, agents, tools, transfers, call records and webhooks. |
Inbound call
PSTN ──► Carrier ──SIP INVITE──► FreeSWITCH ──socket──► inbound-gateway ──reserve──► Orchestrator ──WS audio──► Voice agent
(source, E.164) (DID → tenant, (session) (AI provider)
rules, hours) │
└──tools──► Ocular OS (execute-tool)
- The carrier sends the INVITE to Ocular's SIP edge. Only declared sources are accepted (the carrier's addresses authorized on Ocular's network). An INVITE from an undeclared source is dropped without a reply.
- FreeSWITCH validates the dialed number (DID). It must be in E.164 (
+and country code). Some carriers deliver other formats (for example NANP without+); the edge normalizes them. A DID that cannot be normalized is rejected withCALL_REJECTED. - The inbound-gateway takes the call over an event socket and applies default deny: the DID must exist and be enabled, the tenant must have the
inbounddirection and the country enabled, and the country's jurisdiction pack must be active. If anything is missing the call is hung up. It then checks the service hours configured for that DID. - The call is answered and an agent is reserved. The gateway answers (PCMU codec), creates the attempt with
direction=inboundand asks the orchestrator for a session (POST /sessions/reserve, idempotent per attempt). If there is no capacity it applies the DID's overflow policy: courtesy message and hang up, or queue with music and bounded retries. - Audio is bridged. FreeSWITCH opens an audio fork to the media URL returned by the reservation: 16 kHz mono PCM, 20 ms frames, bidirectional over WebSocket. The agent speaks and listens on that channel; the customer's audio never leaves Ocular's infrastructure toward the AI provider except over that encrypted WebSocket.
- The agent talks and uses tools. Every agent tool is a client tool that the orchestrator forwards to Ocular OS (
execute-tool) with the call context (attempt, conversation, caller number). The OS runs the business logic: scheduling, lookups, assisted transfer, and so on. The model never sees phone numbers or credentials. - Wrap-up. When the agent ends the call (
end_call) or the person hangs up, the orchestrator posts the structured disposition to the engine, the engine releases the session, emits the call events to the bus and, if the tenant has webhooks, delivers them signed (HMAC) to the OS.
Outbound call
Ocular OS ──POST /dial-jobs──► API ──► Scheduler ──► Pacer ──► Originator ──ESL originate──► FreeSWITCH ──SIP──► Carrier ──► PSTN
(legal rules, (capacity, (idempotent (trunk profile,
window, caps) CPS, channels) per attempt) caller ID)
│ answered
└──reserve + WS audio──► Orchestrator ──► Agent
- The OS requests a call with
POST /dial-jobs(one order per contact, of kindcontact,transfer,one_offorrequested). The API answers with a synchronous verdict: accepted, deferred (outside the window) or denied (do-not-call list, attempt cap, no valid numbering class). - The scheduler evaluates the legal rules for the number's country (jurisdiction pack: time window, attempts per number and per contact, rest between attempts, numbering class required for the campaign type) and queues the attempt. Orders with
priority: immediateare dispatched at once; the rest in the incremental pass. - The pacer releases attempts at the rate the limits allow: trunk calls per second, channels, daily budget and sessions available at the orchestrator.
- The originator places the call over SIP through the country's trunk with the campaign's caller ID. If the person answers, it reserves a session and opens the same audio fork as inbound. If there is no answer, busy or failure, it records the result and hangs up.
- Conversation, tools and wrap-up work as in inbound. The OS receives
attempt.finishedby webhook (telephony result, caller ID used, SIP cause) and the agent's disposition.
Transfers today: consult and return
When an agent needs to consult a third party (an advisor, a branch), the OS creates a child order of kind transfer with immediate priority. The engine places a second call to the destination with a liaison agent, while the customer waits on the original call with music and updates. The liaison reports the result and the original agent continues with the customer. In this model the customer's call never moves: it stays anchored at Ocular. The real handoff (connecting the customer to the destination) is described in SIP REFER away from Ocular.
Cross-cutting guarantees
- Default deny at every layer. Network, SIP source, DID format, DID mapping, tenant, country, legal pack, service hours. Anything not explicitly allowed is neither answered nor dialed.
- Legal rules as data, not code. Each country has a pack with windows, caps and numbering classes, activated by a person from legal. Profiles per order kind (one-off call, requested call, transfer) also live in the pack and require a signature.
- Idempotency. Reservations, originations and event deliveries are keyed by attempt; a retry never duplicates a call or a disposition.
- Observability. Every service exposes metrics and structured logs with masked numbers. An operational preflight checks trunks, SIP profiles, certificates and services before and after every deployment.
- No secrets in code or chat. Carrier credentials, orchestrator tokens and webhook keys live in a secrets manager and are injected per environment.