SIP REFER away from Ocular (and alternatives)
How to take a call out of Ocular and leave it at a public-network destination: a human advisor, a branch, a number owned by the customer. This page describes the current state, the technical options (blind SIP REFER, attended REFER, bridge at Ocular, 302 redirect), what each one requires from the carrier and how to choose.
No real IPs, hosts, numbers or credentials. Transfer destinations are never written by the model: they are resolved server-side from a list configured per project.
Current state
Today Ocular does not execute SIP REFER. What exists is the consult transfer (see Agent call flow): the agent asks to consult a destination, the engine opens a second call with a liaison agent, the customer waits with music on the original call and the result comes back to the agent. The customer's call always stays anchored at Ocular.
The real handoff, connecting the customer to the destination so that Ocular is no longer in the middle, is designed (orchestrator contract v1.1, blind and attended modes, destination allowlist per tenant and DID, failure policy) but not built. This page captures that design and the alternatives, so the decision can be made with the carrier.
The options
1. Blind REFER (blind transfer)
Ocular sends the carrier, inside the call's dialog, a REFER with Refer-To: sip:<E.164 destination>@<carrier>. The carrier answers 202 Accepted, originates the new leg to the destination, reports progress with NOTIFY (100, 180, 200) and, when the destination answers, Ocular's leg receives BYE. Audio stops flowing through Ocular.
Customer ──PSTN── Carrier ──SIP── Ocular (agent)
│ ◄── REFER (Refer-To: destination)
│ ──► 202 Accepted
│ ──► INVITE destination ... 200 OK
│ ──► NOTIFY (200 OK) to Ocular, then BYE
Customer ──PSTN── Carrier ──PSTN── Destination (Ocular is no longer on the call)
In FreeSWITCH, on an already-answered call, this is the deflect application (or uuid_deflect <uuid> <sip-uri> over ESL), which sends the REFER within the existing dialog.
| Pros | Frees the channel, the AI session and bandwidth at Ocular; no audio "tromboning"; a single billed leg after the handoff (carrier dependent). |
| Requires from the carrier | Support for REFER from the called side (most wholesale carriers accept it only from the originating side; many answer 403, 603 or 501). Allowing Refer-To to be an arbitrary PSTN number on the account, and billing the new leg to the partner's account. |
| Risks | Ocular loses visibility and control once the REFER is accepted (no recording or disposition for the final leg). If the destination does not answer, the carrier may return the call to Ocular with NOTIFY 4xx/5xx or drop it; both must be handled. |
| When | A carrier that confirms in-dialog REFER support from the callee, and a partner that does not need Ocular to stay on the call. |
2. Attended REFER (attended transfer)
Ocular first opens a second call to the destination over its trunk (consult), and when the destination accepts, sends the carrier a REFER whose Refer-To includes ?Replaces=<Call-ID of the consult>. The carrier joins the two legs and Ocular leaves. This is the variant today's consult would leave ready: the second call already exists.
| Pros | The customer never lands on a destination that does not answer; Ocular confirms before letting go. |
| Requires from the carrier | Everything blind REFER requires plus support for Replaces between two dialogs of the same account. This is the least supported by wholesale carriers. |
| When | Same carrier on both legs and explicit confirmation of Replaces. |
3. Bridge at Ocular ("handoff" in the engine)
Ocular originates a leg to the destination over its outbound trunk (the country's trunk, with the campaign's caller ID) and, when it answers, bridges the two legs in FreeSWITCH (uuid_bridge). Ocular stays in the audio path until one of the parties hangs up.
Customer ──PSTN── Carrier ──SIP── Ocular ──SIP── Outbound trunk ──PSTN── Destination
│ uuid_bridge (RTP flows through Ocular)
| Pros | Works with any carrier, no REFER negotiation. Ocular keeps control: it can record with consent, measure, return to the agent if the destination hangs up, apply service hours and the allowlist to the destination with the same rules as an outbound call. It is the phase 2 already foreseen in the transfer contract (mode: "handoff"). |
| Cost | Two billed legs for the duration of the call and a busy channel at Ocular. Minimal extra audio latency. |
| Requires from the carrier | Nothing new: it uses the existing outbound trunk. If the inbound leg arrives through an inbound-only carrier (like the first partner's TLS profile), the outbound leg goes through the country's trunk. |
| When | Default option while the carrier has not confirmed REFER, or whenever supervision, recording or return-to-agent is needed. |
4. Redirect before answering (SIP 302)
If the decision of where to send the call can be made before answering (by hours, by DID, by load), Ocular replies to the INVITE with 302 Moved Temporarily and Contact: sip:<destination>@<carrier>. The carrier reroutes and Ocular never answers.
| Pros | Zero resources at Ocular, no REFER. Useful for after-hours overflow to a human. |
| Limits | Pre-answer only: useless once the agent has already talked. Depends on the carrier accepting 302 toward PSTN (most do). |
5. What is not a transfer
- Re-INVITE changes media parameters (codec, direction, RTP IP); it does not move the call.
- In-platform transfer (the AI agent hands the conversation to a human on Ocular's web console): audio keeps entering Ocular over SIP; who talks changes, signaling does not. This is the shortest option when the human is an Ocular operator and not a PSTN number.
Quick comparison
| Criterion | Blind REFER | Attended REFER | Bridge at Ocular | 302 pre-answer |
|---|---|---|---|---|
| Carrier dependency | High | Very high | None | Low |
| Ocular leaves the call | Yes | Yes | No | Yes (never joined) |
| Visibility and recording of the final leg | No | No | Yes | No |
| Return to agent on failure | Limited | Yes (before letting go) | Yes | No |
| Channel/minute cost | Minimal | Minimal | Two legs | Zero |
| Status at Ocular | Designed | Designed | Designed (phase 2) | Not evaluated |
What to confirm with the carrier before choosing REFER
- Does it accept in-dialog
REFERsent by the called side (Ocular is the callee on inbound)? - Can
Refer-Tobe any PSTN number in E.164, or only numbers on the account? - Does it return
NOTIFYwith progress and the final result? What happens if the destination does not answer: does the call come back or get dropped? - Does it support
Replacesfor attended transfer? - How is the new leg billed, and which caller ID is presented to the destination (the original customer's, the partner's, Ocular's)? This has legal implications in Chile and the United States.
- Is there a time limit between
202 Acceptedand theBYE? - Can they provide evidence of a test REFER (Call-ID, codes, NOTIFY)?
If any of answers 1, 2 or 3 is negative or uncertain, choose the bridge at Ocular.
Reference design in the engine (contract v1.1, not yet built)
- Signal from the orchestrator to the engine over the media WebSocket control channel:
{ "type": "transfer", "to": "<E.164 or SIP URI>", "mode": "blind" | "attended", "reason": "…" }. The destination is resolved server-side from the agent's configuration in Ocular OS; the model only picks adestination_id. - Destination allowlist per tenant and DID, default deny. With an empty list the transfer fails closed.
- Failure policy per DID:
return_to_agent,voicemailorcourtesy_hangupwhen the REFER is rejected or the destination does not answer. - Legal gates applied to the destination as to any outbound call: time window, do-not-call list, numbering class, pilot allowlist. The
transferprofile of the jurisdiction pack exempts attempt caps and rest periods, not the other rules. - Attempt states:
TRANSFERRING→TRANSFERRED(or back toIN_CONVERSATIONif the return policy applies). - Events:
transfer.initiatedandtransfer.completedwith the REFER's SIP code (202,4xx) and whether a fallback was applied. Delivered by webhook to the OS like every other event. - Disposition:
outcome: transferred_humanwithtransfer { to, mode, completed_at }. - Execution in FreeSWITCH:
deflectfor blind, origination +REFERwithReplacesfor attended,uuid_bridgefor the bridge. The audio fork is stopped before moving the call. - Tests: a SIPp scenario simulating a carrier that accepts and one that rejects the REFER, against the mock orchestrator.
Recommendation
Build the bridge at Ocular first, as mode: "handoff" of the transfer contract: it does not depend on the carrier, it reuses the existing consult (the second leg is already opened today) and it keeps recording and return-to-agent. Leave blind REFER as a per-carrier optimization, enabled per DID, once the carrier confirms points 1 to 3 above in writing and a test with evidence exists.