1. Honeypot
CallerAPI Documentation
  • Quickstart
  • Use cases
    • For carriers (MNOs/MVNOs)
    • CPaaS platforms
    • Cloud communications providers
    • SIP trunking providers
    • PBX/Cloud PBX
    • UCaaS vendors
  • Account
    • Balance and email
      GET
  • Spam protection
    • Voice firewall
      • Get started
      • Quickstart
        • What you get
        • Before you start
        • Test with a recording
        • Connect your switch
        • Switch notes
        • Twilio and Telnyx
        • Send text instead of audio
      • Verdicts
        • Read a verdict
        • What to do with a verdict
        • Block a caller
        • Events and webhooks
      • Honeypot
        • Hand a call over
        • Audio, events, and limits
      • Reference
        • Endpoints
        • Errors
        • Limits and thresholds
        • Production checklist
      • REST
        • What this deployment can do
        • List the verdict categories
        • List the honeypot personas
        • Score a transcript or a recording
        • List your recent sessions
        • Get one session with verdict and intel
        • Twilio voice URL for a screened number
        • Preview the Twilio TwiML
        • Telnyx voice URL for a screened number
        • Twilio voice URL for a honeypot number
        • Telnyx voice URL for a honeypot number
      • WebSocket
        • Live scam filter stream
        • Honeypot stream
    • Daily spam reports
      • Webhook
        • Subscribe to daily reports
        • Unsubscribe from daily reports
        • List webhook subscriptions
        • Manual dispatch of reports
        • Test webhook
      • REST
        • Fetch daily spam reports
    • 15 days spam CSV snapshot
      GET
    • Spam score + HLR
      GET
  • Mobile SDK
    • Get started
    • Quickstart
      • What you get
      • Get your keys
      • Android
      • iOS
      • Flutter
      • React Native
      • Check it works
    • Call screening
      • What each platform can do
      • Android call screening
      • iOS prerequisites
      • iOS add the extension
      • iOS test on device
    • Reference
      • Methods
      • Errors
      • Limits and billing
      • Troubleshooting
  • Data partners
    • Partner tems & docs
    • Upload spam reports
    • Upload contacts
  • Fraud prevention
    • Ported date
    • Porting history
    • Online presence
    • KYC user identity
  • Schemas
    • Spam protection
      • Spam score request
      • Business info
      • Carrier info
      • Complaint (without number)
      • Daily spam reports request
      • Complaint (with phone)
  1. Honeypot

Hand a call over

The honeypot answers the call as a persona. It keeps the caller busy, extracts intel, and files the number. Every minute a scammer spends with the persona is a minute not spent on a real victim.
It uses the same connections as the filter. The difference is direction. The filter listens. The honeypot listens and speaks.
Check honeypot is true in What this deployment can do first.

Pick a path#

You haveHowTime
A domain on the CallerAPI SIP firewallSet spam_action=honeypot on the domain. Spam calls are answered by a persona instead of a 603. No INVITE from you is needed.1 minute
A SIP switchSend an INVITE to sip:honeypot@honeypot.callerapi.com:5080.10 minutes
A Twilio numberVoice URL https://api.callerapi.com/api/voice/honeypot/twiml?key=YOUR_KEY.5 minutes
A Telnyx numberVoice URL https://api.callerapi.com/api/voice/honeypot/texml?key=YOUR_KEY.5 minutes
A media server with a WebSocketOpen wss://api.callerapi.com/api/voice/honeypot/stream?key=YOUR_KEY.See Audio, events, and limits

On the SIP firewall#

spam_actionEffect
honeypotSpam INVITEs to this domain are answered by a persona. Billed per minute.
declineSpam INVITEs get 603 Declined.
defaultFollow the fleet default.
Your switch never rings for these calls. Media runs between the carrier and the honeypot. Your switch must accept G.711 (PCMU or PCMA) and must not expect SRTP or re-INVITEs on these calls.

Over SIP from your own switch#

1.
Send an INVITE to sip:honeypot@honeypot.callerapi.com:5080.
2.
Offer PCMU or PCMA. PCMU is preferred when both are present. No SRTP.
3.
Add X-CallerAPI-Key: YOUR_KEY. Without an account the call is refused.
4.
Optional: add X-Persona, X-Webhook, X-Report.
The caller's number is read from P-Asserted-Identity, then from From. RFC 4733 DTMF is understood. The honeypot ends the call with BYE.
Calls that arrive through the SIP firewall are attributed by the domain in the To header. They need no key header.

On Twilio or Telnyx#

Set the number's voice URL as in the table above. The endpoint returns TwiML or TeXML that connects the call to the honeypot in both directions. The call is answered and stays up until the persona hangs up.
Endpoint reference: Twilio voice URL for a honeypot number and Telnyx voice URL for a honeypot number.

Options#

As URL parameters, in params of the start message, or as SIP headers.
OptionSIP headerDefaultMeaning
personaX-PersonarandomA persona id from List the honeypot personas.
webhookX-WebhooknoneHTTPS URL for events.
reportX-ReporttrueFile the caller when the final score reaches 0.8.
Next: Audio, events, and limits.
Modified at 2026-09-18 16:57:04
Previous
Events and webhooks
Next
Audio, events, and limits
Built with