Documentation
Concepts
A call you route through Open Voice Shield is relayed to your own destination and recorded while it is relayed; after the hang-up the recording is decoded, transcribed with the two parties on separate channels, and assessed by a language model. The result is one record per call carrying a probability from 0 to 100, a category, the caller's claimed identity, numbered red flags, a TCPA comment, a plain 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 never affects a call — it 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 — the SIP integration guide lists them.
- 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.
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.
- Only G.711 (A-law and µ-law) 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.
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. |
| 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, not just 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. |
| 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 not the same thing: the score is how confident the assessment is that the call is abusive, 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. |
There is a third case worth knowing: 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 on a threshold. Every new account starts with one enabled: probability 90 or above and a block recommendation. |
| 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 a platform setting your operator configures, not a per-call one. The defaults the platform ships with:
| Artefact | 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 the operator's configured schedule |
Because the media path carries your RTP, the audio of every analyzed call passes through Open Voice Shield and is written to storage. That is inherent to the product: 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.
Next: the API reference for the exact request and response shapes, or Security for isolation, access and deletion.