Honeypot stream

Hand a call to a persona. The honeypot listens and speaks. It keeps the caller busy, extracts intel, and files the number. Same protocol as the filter stream, plus audio back.

Auth. ?key=YOUR_KEY on the URL, or the X-Auth header. 401 when the key is missing or wrong. 503 when honeypot is false in GET /api/voice/capabilities or this node is at its session limit. On 503, retry on a new connection.

Cost. 8 credits per started minute. 4 more per minute on a number CallerAPI provides.

1. Send the start message

One text frame within 10 seconds, before any audio. Same fields as the filter stream. params may carry persona, webhook, and report.

{
  "type": "start",
  "call_id": "your-call-id",
  "from": "+15559990000",
  "to": "+15551234567",
  "sample_rate": 8000,
  "encoding": "mulaw",
  "params": { "persona": "grandma_edna", "webhook": "https://example.com/hook", "report": "true" }
}

2. Audio both ways

Send the caller's audio as binary frames in your encoding and sample rate.

Receive the persona's audio as binary frames in the same encoding and rate. Play it to the caller.

On {"type":"clear"}, drop any queued playback. The caller interrupted the persona.

{"type":"mark","name":"..."} is advisory. Ignore it if you do not need it.

Do not send the persona's own voice back. Send the caller only.

3. Optional client text frames

Message	Meaning
`{"type":"transcript","text":"..."}`	Words you transcribed yourself.
`{"type":"dtmf","digit":"1"}`	A key press.
`{"type":"stop"}`	The call ended. Closing the socket has the same effect.

4. Receive events

Text frames with a type field, the same as the filter stream, plus:

`type`	When	Extra fields
`session.started`	Accepted. Carries the `persona` object.	`persona`
`session.error`	Speech synthesis or a model refused a request. Ends the session only when the greeting could not be spoken.	`error`, `text`

session.ended carries the verdict, the intel, and the transcript with the persona's name as one speaker and caller as the other. reported_numbers counts the caller plus every callback number filed.

5. Limits

A honeypot call lasts at most 15 minutes.

The persona prompts the caller after 8 seconds of silence. After three unanswered prompts it hangs up.

report defaults to true. The filing threshold is a score of 0.8. none, Advertising, Surveys, Hang Up, and No Subject Provided are never filed. Other needs 0.85.

Other ways in

SIP: send an INVITE to sip:honeypot@honeypot.callerapi.com:5080 with G.711 (PCMU or PCMA). Add X-CallerAPI-Key: YOUR_KEY. X-Persona, X-Webhook, and X-Report carry the same options.

CallerAPI SIP firewall: set spam_action=honeypot on your domain. No INVITE from you is needed.

Twilio and Telnyx Media Streams are accepted on this URL. Use POST /api/voice/honeypot/twiml or /texml to get the vendor XML.

1. Send the start message#

2. Audio both ways#

3. Optional client text frames#

4. Receive events#

5. Limits#