Skip to main content

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.

ProsFrees the channel, the AI session and bandwidth at Ocular; no audio "tromboning"; a single billed leg after the handoff (carrier dependent).
Requires from the carrierSupport 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.
RisksOcular 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.
WhenA 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.

ProsThe customer never lands on a destination that does not answer; Ocular confirms before letting go.
Requires from the carrierEverything blind REFER requires plus support for Replaces between two dialogs of the same account. This is the least supported by wholesale carriers.
WhenSame 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)
ProsWorks 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").
CostTwo billed legs for the duration of the call and a busy channel at Ocular. Minimal extra audio latency.
Requires from the carrierNothing 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.
WhenDefault 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.

ProsZero resources at Ocular, no REFER. Useful for after-hours overflow to a human.
LimitsPre-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​

CriterionBlind REFERAttended REFERBridge at Ocular302 pre-answer
Carrier dependencyHighVery highNoneLow
Ocular leaves the callYesYesNoYes (never joined)
Visibility and recording of the final legNoNoYesNo
Return to agent on failureLimitedYes (before letting go)YesNo
Channel/minute costMinimalMinimalTwo legsZero
Status at OcularDesignedDesignedDesigned (phase 2)Not evaluated

What to confirm with the carrier before choosing REFER​

  1. Does it accept in-dialog REFER sent by the called side (Ocular is the callee on inbound)?
  2. Can Refer-To be any PSTN number in E.164, or only numbers on the account?
  3. Does it return NOTIFY with progress and the final result? What happens if the destination does not answer: does the call come back or get dropped?
  4. Does it support Replaces for attended transfer?
  5. 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.
  6. Is there a time limit between 202 Accepted and the BYE?
  7. 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 a destination_id.
  • Destination allowlist per tenant and DID, default deny. With an empty list the transfer fails closed.
  • Failure policy per DID: return_to_agent, voicemail or courtesy_hangup when 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 transfer profile of the jurisdiction pack exempts attempt caps and rest periods, not the other rules.
  • Attempt states: TRANSFERRING → TRANSFERRED (or back to IN_CONVERSATION if the return policy applies).
  • Events: transfer.initiated and transfer.completed with 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_human with transfer { to, mode, completed_at }.
  • Execution in FreeSWITCH: deflect for blind, origination + REFER with Replaces for attended, uuid_bridge for 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.