Documentation
Concepts
Ask AI about this page
A call routed through Open Voice Shield is relayed to your destination and recorded on the way. After hangup it is transcribed on separate channels and assessed by a language model. One record per call: a probability, a category, red flags, a TCPA comment, a summary and a block, review or allow recommendation.
A call has two halves#
Everything that touches the live call is synchronous and fast: authorize, anchor the media, relay, tear down. Everything that produces a verdict happens after the BYE, on a worker. A failure in the second half marks the analysis failed and leaves the call itself untouched.
While the call is up#
- Admission. The source address must be whitelisted, the account active and not blocked for that caller ID, the balance sufficient and a port free. Each check has its own SIP response, listed in the SIP integration guide.
- Routing. A destination is chosen from your rules and the call is relayed there unchanged, apart from a tech prefix if the destination carries one.
- Media. The RTP is anchored, so it flows through us in both directions for the whole call. This is what makes a recording possible, and it means your audio traverses our media path.
- Teardown. A BYE from either side ends the call. A call can also be ended by the credit cut-off or the maximum lifetime, in which case BYE goes to both parties.
The record starts before the verdict does
The call record exists from the moment the call is authorized. Duration, billed seconds, SIP code, end reason, the destination chosen, the route prefix and the SIP log are all there whether or not an analysis is ever produced.
Watching a call while it is up#
On the Live page every licensed port is an indicator. Click a lit one and a line inspector opens beneath the bank for that call, polling every two seconds while the call is up:
- Signalling: the SIP ladder as the proxy traces it, one row per message, and the codec, post-dial delay and answer delay read from it the moment the 180/183 and 200 arrive.
- Media: the two RTP legs from the relay's own counters, packets and packet rate per leg; jitter, loss, round-trip time and a MOS when the far end reports them in RTCP, shown as not yet reported when it does not.
- After hang-up: the same panel shows decode, transcription and analysis completing, the quality measured from the recording per leg, who ended the call with the Q.850 cause, and the verdict.
The panel reads GET /calls/{id}/inspect, which bundles the ladder, the live timings, the relay's per-leg statistics, the pipeline state and the verdict; see the API reference.
Recording#
The relayed audio is captured as it passes and, after the call, decoded into a single stereo WAV at 8 kHz: one channel per direction. That separation is physical, not statistical: the caller's channel is the caller's RTP stream, so there is no speaker diarization to get wrong.
- G.711 (A-law and µ-law), G.722, G.729 and G.723.1 can be decoded; other codecs relay fine but leave nothing to transcribe.
- Comfort-noise and telephone-event payloads are ignored when decoding speech.
- The finished WAV is downloadable from the call record and included in the export bundle.
- Calls shorter than the minimum analysis length, 5 seconds by default, are recorded and billed but not analyzed.
Call quality (QoS)#
Alongside the verdict, each analyzed call records how the media actually travelled. The metrics are computed from the RTP capture at decode time, per leg (caller and callee), and the worst leg becomes three fields on the call record, shown in the portal and quoted in the alert email:
| mos | Estimated MOS (1.00 to 4.50) via the E-model, derived from packet loss and jitter. A transport-quality estimate, not a perceptual audio score. |
|---|---|
| jitter_ms | RFC 3550 interarrival jitter in milliseconds, worst-leg average. |
| packet_loss_pct | Packets lost as a percentage of packets expected, worst leg. |
Calls from before the feature, or whose media capture had already expired under retention, carry no values: an empty field means not measured, never zero.
An alert rule can fire on this figure: set it to alert on poor call quality, or on fraud or poor quality, with the estimated MOS ceiling you choose. A call that was not measured never triggers it.
Signalling on the record#
The same call record also carries what the signalling showed, taken from the SIP messages the proxy traced and from what it saw at hangup. These answer the second question after a bad MOS: was the route slow to ring, did the far end play early media, and who ended the call.
| codec | The negotiated audio codec (PCMU, PCMA, G722, G729, G723, mixed, or the payload type when unnamed). From the RTP the decode stage parsed, else from the answer SDP. Explains a missing verdict and a low MOS in one glance. |
|---|---|
| pdd_ms | Post-dial delay: INVITE to the first 180 or 183, in milliseconds. The figure route buyers compare vendors on. |
| answer_delay_ms | INVITE to 200 OK, in milliseconds. |
| early_media | Whether a 183 with SDP arrived before the answer. A known signal in delayed-playback FAS. |
| hangup_by | caller, callee or system: the side that sent the BYE, or the platform for a credit cut-off, a lifetime limit or a failure it generated itself. |
| q850_cause | , q850_textThe Q.850 cause and text from the Reason header of the BYE or the final response, when the party sent one. |
Every one of these is empty when it could not be measured: a call traced before the feature, or a trace that retention has already pruned. Empty means not measured, never zero.
Transcription#
Each channel is transcribed on its own and the timed segments of both are merged by start time into one speaker-labelled text:
the transcript text, as stored
CALLER: Hi, I'm calling from the card services department about your account.
CALLEE: Which account is that?
CALLER: The one ending in the last four digits you'll confirm for me now.| Field | Means |
|---|---|
| text | The merged, speaker-labelled transcript shown above. |
| segments | Each utterance with its speaker (caller or callee) and its start and end in seconds. |
| language | Detected language of the speech, as an ISO 639-1 code. |
| audio_seconds | Seconds of audio actually transcribed. |
| location | Where the stage ran: local (on the server) or cloud. |
A channel that carries only digital silence is skipped, which is why a leg that never speaks produces a one-sided transcript rather than an error.
The analysis#
The transcript is assessed against a fraud and telemarketing-compliance prompt and returned as a fixed set of fields. Every field is always present. A field with nothing to say is an empty string or an empty list.
| Field | What it is | How to use it |
|---|---|---|
| title | A short headline for the call. | The line in a queue or an alert. Never the basis for a decision. |
| probability | 0–100: how likely this call is a scam or illegal/abusive telemarketing. | The number you threshold on for automation and alerting. |
| category | One of a fixed list, see categories. | Grouping and reporting: which kind of abuse is on your network. |
| entity | The organization the caller claimed to represent, or empty. | Impersonation signal. A bank's name here on a 90-probability call is the story. Click it on the calls list to see every call that named it. |
| caller_identity | How the caller identified themselves, name, role, or empty. | Compare with the ANI and with what the entity would actually use. |
| red_flags | Numbered, concrete observations taken from the transcript. | The evidence. Read these before acting; they are what you quote to the customer. |
| tcpa_comment | Assessment against TCPA and the FTC Telemarketing Sales Rule, identification, opt-out, consent, robocall. | Compliance review of legitimate campaigns, as well as fraud. |
| summary | Two to five sentences on what happened. | What a reviewer reads first, and what goes into a case. |
| recommendation | block review allow | The suggested action. Automation rules match on it. |
| language | Primary spoken language, ISO 639-1. | Routing a review queue to someone who speaks it. |
| keywords | Three to ten short keywords characterizing the call. | Search and clustering across many calls. Click one on the calls list to filter by it; the most frequent ones are offered under the search. |
| location | local or cloud, where the assessment ran. | Data-handling questions. Vendor and model names are not exposed on a call. |
Reading the probability#
The probability and the recommendation are related but different. The score is how confident the assessment is that the call is abusive, and the recommendation is what to do about it. When a model returns no usable recommendation, the score decides it: 70 and above is block, 40 and above is review, below that allow.
| Band | Typically | Operations response |
|---|---|---|
| 90–100 | block | Alert, and let an automation rule hold the ANI while a human confirms. |
| 70–89 | block or review | Same-day human review. Open a case if the red flags hold up. |
| 40–69 | review | Sample it. This band is where compliance problems live, not outright fraud. |
| 0–39 | allow | Nothing. Keep it for reporting and for trend lines. |
Categories#
The category is one of a fixed list, so it can be counted and charted:
- credit_card_scam
- tech_support_scam
- government_impersonation
- bank_impersonation
- debt_collection
- prize_lottery_scam
- utility_scam
- telemarketing_compliant
- telemarketing_noncompliant
- robocall
- legitimate_business
- personal
- unknown
unknown is what you get when the call gave the assessment nothing to go on, a wrong number, an IVR, thirty seconds of hold music.
When there is no verdict#
Two fields on the call say where the pipeline got to: transcript_status and analysis_status.
| Value | Means |
|---|---|
| pending | Queued or waiting for a retry. Normal for the first minute after hang-up. |
| processing | Running now. |
| done | There is a result. |
| skipped | Nothing to analyze: the call was never answered, or was shorter than the minimum analysis length. |
| failed | Every attempt failed. processing_error on the call says why. |
One more case: when the assessment runs but returns nothing usable, the call gets a deliberate fail-safe result instead of a missing one, probability 50, category unknown, recommendation review, and a red flag saying the analysis could not be completed. It never fails towards allow.
Acting on a verdict#
A verdict is an aid to a reviewer, not a judgment. Read the transcript before acting on a score. What is available to act with:
| Mechanism | What it does |
|---|---|
| Alert rules | E-mail, a Slack channel, or both, on a threshold. Every new account starts with one enabled: probability 90 or above and a block recommendation. A rule can also fire on call quality, when the call's estimated MOS is at or below a ceiling you set, or on either condition. |
| Automation rules | Match a minimum probability and a set of recommendations, then either block the caller ID or divert it to another destination, for a set number of hours. Enforcement happens on the next call from that ANI, at admission. |
| Webhooks | A signed call.analyzed event, so your own systems act without polling. |
| Export bundle | One zip per call, the analysis as JSON, the transcript, the recording, the SIP log and a readable report, openable by someone with no account. |
A blocked caller ID is enforced at admission
While a block control is in force, the next call from that ANI is refused with 403 Blocked by rule before it is routed anywhere, and unlike other refusals it is written to your call records, so you can see what the rule stopped.
What is kept, and for how long#
Retention is set platform-wide, not per call, and is not something you configure. The windows in force:
| Artifact | Default |
|---|---|
| Recording (WAV) | 30 days |
| Source media captures | Discarded as soon as the recording has been decoded from them |
| Transcript, analysis, call record | Kept with the call record |
| SIP log | Pruned on a platform schedule |
The audio of every analyzed call passes through Open Voice Shield and is written to storage. There is no analysis without a recording. If your audio must never leave your own network, this is not the right tool for the job.
Frequently asked questions#
What does the fraud probability mean?
An integer from 0 to 100 for how likely the call is a scam or illegal or abusive telemarketing. It is the number you threshold on for alerts and automation. When a model returns no usable recommendation, the score decides it: 70 and above is block, 40 and above is review, below that allow.
What is the difference between the probability and the recommendation?
The probability is how confident the assessment is that the call is abusive. The recommendation, block, review or allow, is what to do about it. Automation rules match on the recommendation and a minimum probability together.
What happens when the analysis cannot produce a verdict?
The call gets a deliberate fail-safe result instead of a missing one: probability 50, category unknown, recommendation review, and a red flag saying the analysis could not be completed. It never fails towards allow.
Why is the transcript split by speaker so reliably?
Because the separation is physical, not statistical: each direction of the call is its own RTP stream, decoded to its own channel and transcribed on its own, so there is no speaker diarization to get wrong.
How long are recordings and transcripts kept?
Recordings are kept 30 days by default, and source media captures are discarded as soon as the recording has been decoded from them. The transcript, the analysis and the call record are kept with the call. SIP logs are pruned on a platform schedule.
Next: the API reference for the exact request and response shapes, or Security for isolation, access and deletion.