Skip to main content

Detect Scam Call

API URL: wss://api.hiyaapi.com/v1/voice-scam-protection/detect-scam-call

This API analyzes the call based on its speech content, voice synthesis and call metadata.

See the overview page for general information about the voice scam protection APIs.

Initial metadata schema
Event schema

Example session​

# 1. → Client sends initial metadata
{
  "sampleRate": 8000,
  "phone": "+15555550000",
  "userPhone": "+15555550001",
  "direction": "Incoming",
  "isContact": true,
  "sipMethod": "INVITE",
  "sipHeaders": {
    "Via": "SIP/2.0/UDP 10.0.0.0:5060;branch=z9hG4bK000000000",
    "Max-Forwards": "70",
    "From": "\"Alice\" <sip:+15555550000@example.com>",
    "To": "\"Bob\" <sip:+15555550001@example.com>",
    "Call-ID": "4a32e052-3024-4e9b-919b-0b9b543c4730",
    "CSeq": "1 INVITE",
    "Diversion": "<sip:+15555550010@example.com>",
    "Contact": "\"Alice\" <sip:+15555550000@10.0.0.0:5060>",
    "P-Asserted-Identity": "\"Alice\" <sip:+15555550000@example.com>",
    "Content-Length": "0"
  }
}

# 2. ← Server sends session metadata event
{"type": "sessionMetadata", "sessionId": "838e90ff-ddaf-4c73-8bac-1e380137d99e"}

# 3. → Client sends audio frame
# 4. → Client sends audio frame
# 5. → Client sends audio frame

# 6. ← Server sends transcript line
{ "type": "transcript", "speaker": "USER", "transcript": "hello who is this" }

# 7. ← Server sends result event
{
  "type": "result",
  "callScamRisk": "NOT_SCAM",
  "callOriginatorRisk": "MEDIUM",
  "scamDialog": {
    "scamDialogRisk": "NEUTRAL",
    "confidence": "LOW"
  },
  "syntheticVoice": {
    "syntheticVoiceDetected": "NO",
    "score": 0.98
  }
}

# 8. → Client sends audio frame
# 9. → Client sends audio frame

# 10. ← Server sends transcript line
{ "type": "transcript", "speaker": "SUBJECT", "transcript": "hello this is your bank we have frozen your bank account" }
{ "type": "transcript", "speaker": "SUBJECT", "transcript": "i am going to need your social security number to unlock it" }

# 11. ← Server sends result event
{
  "type": "result",
  "callScamRisk": "HIGH_SCAM_RISK",
  "callOriginatorRisk": "MEDIUM",
  "scamDialog": {
    "scamDialogRisk": "SCAM",
    "confidence": "HIGH"
  },
  "syntheticVoice": {
    "syntheticVoiceDetected": "NO",
    "score": 0.97
  }
}