Connect your switch

The plain WebSocket protocol. Your side sends one JSON line and then binary audio. Our side sends JSON events. Read the steps in order. Step 2 is the one most integrations get wrong.

Before this page, run Test with a recording. It is a working client.

Step 1: open the socket

wss://api.callerapi.com/api/voice/filter/stream?key=YOUR_KEY

Optional URL parameters. You may also send them in the params object of the start message. A value in the start message wins over the URL.

Parameter	Values	Default	Meaning
`webhook`	HTTPS URL	none	Receives events. HTTP URLs are ignored.
`language`	BCP-47 code, for example `en`	auto	Transcription hint. Set it when you know the language.
`report`	`true` or `false`	`false`	Files the caller when the final level is `scam`.

The upgrade is refused with 401 when the key is missing or wrong. It is refused with 503 when live_filter is false or when this node is at its live session limit. On 503, retry on a new connection.

Step 2: send the start message

Send one text frame within 10 seconds of the connection. Send it before any audio. A binary frame before the start message closes the socket.

{
  "type": "start",
  "call_id": "your-call-id",
  "from": "+15559990000",
  "to": "+15551234567",
  "sample_rate": 8000,
  "encoding": "pcm16",
  "params": {
    "webhook": "https://example.com/callerapi-voice",
    "language": "en",
    "report": "false"
  }
}

Field	Required	Notes
`type`	yes	Always `start`.
`call_id`	no	Your identifier for the call. It is echoed in every event and stored with the session. Use the SIP Call-ID or your CDR key.
`from`	for `report`	Caller number in E.164 with a leading `+`. The block action uses it. Without it, only callback numbers can be filed.
`to`	no	Called number in E.164.
`sample_rate`	no	8000 to 48000. Default 8000.
`encoding`	no	`pcm16` (16-bit little-endian, default) or `mulaw` (G.711 mu-law).
`params`	no	Same keys as the URL parameters. Values are strings.

Take from from P-Asserted-Identity when the trunk sends it, then from From. Normalize it to E.164 before you send it.

Step 3: send audio

Send the caller's audio as binary frames in the encoding and sample rate you declared. Nothing else is needed. The server does not acknowledge audio frames.

Send the remote caller's audio only. Every binary frame is treated as the caller.

Do not mix both parties into one channel.

Send frames of 20 ms to 200 ms. Shorter frames waste bandwidth. Longer frames add latency.

Send frames in real time. The transcriber expects live pace.

Empty binary frames are ignored.

The bit rate is 128 kbit/s for pcm16 at 8 kHz and 64 kbit/s for mulaw. If your switch already has G.711 mu-law, send it as mulaw and skip the transcode.

Step 4: read events

The server sends events as text frames. Each is one JSON object with a type field. The filter never sends binary frames.

`type`	When	Extra fields
`session.started`	The start message was accepted.
`transcript.line`	One utterance is final.	`speaker`, `text`
`verdict`	The score changed enough to matter.	`verdict`
`session.ended`	The call ended and the final analysis is done.	`verdict`, `intel`, `transcript`, `duration_seconds`, `reported`, `reported_numbers`

Every event carries session_id, kind, call_id, from, to, and at. Store session_id. It is the key for Get one session. Full details are on Events and webhooks.

Step 5: act on the verdict

Read the level field. Decide once per level and keep it simple.

Level	Score	Suggested action
`clean`	below 0.3	Nothing.
`suspicious`	0.3 to 0.59	Tag the CDR.
`likely_scam`	0.6 to 0.84	Warn the called party. Consider recording.
`scam`	0.85 and above	Warn or drop the call.

The filter never acts on the call. Your switch does. What to do with a verdict has the playbook.

Step 6: send DTMF (optional)

{"type": "dtmf", "digit": "1"}

Digits are collected in order into intel.dtmf. A caller who asks the victim to "press 1 to speak to an agent" leaves a trace this way.

Step 7: end the call

Send {"type": "stop"} or close the socket. The server then:

Flushes transcription.

Runs the final analysis on the full transcript. This takes up to 20 seconds.

Files the caller when report=true and the final level is scam.

Sends session.ended on the socket and to the webhook.

Closes the socket.

Keep the socket open until you receive session.ended, or read it from the webhook, or read it later from Get one session.

A filter session ends by itself after 60 minutes.

Step 8: add a webhook

Most media forks do not expose socket messages to the dialplan. Set webhook to an HTTPS URL on your own backend and act on events there. The server posts every event except transcript.line.

Verify X-Voice-Signature on every post. Events and webhooks has the header list and verification code.

Step 9: turn on blocking

Set report=true only after you have watched verdicts on your own traffic for a few days. Filing is consequential. See Block a caller.

Next: Switch notes for FreeSWITCH, Asterisk, Kamailio, and SBCs.

Step 1: open the socket#

Step 2: send the start message#

Step 3: send audio#

Step 4: read events#

Step 5: act on the verdict#

Step 6: send DTMF (optional)#

Step 7: end the call#

Step 8: add a webhook#

Step 9: turn on blocking#