API Request & Response¶

The ScamShield AI honeypot exposes a single POST endpoint that receives scammer messages and returns persona-driven replies while extracting intelligence.

Endpoint¶

POST https://asia-south1-your-gcp-project-id.cloudfunctions.net/guvi_honeypot

Request Headers¶

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`
`x-api-key`	Yes	Your ScamShield API key

curl -X POST https://asia-south1-your-gcp-project-id.cloudfunctions.net/guvi_honeypot \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SCAMSHIELD_API_KEY" \
  -d '{ ... }'

Request Body¶

{
  "sessionId": "session-abc-123",
  "message": {
    "sender": "scammer",
    "text": "Your SBI account has been blocked. Share OTP to unblock.",
    "timestamp": 1700000000
  },
  "conversationHistory": [
    {
      "sender": "scammer",
      "text": "Hello, this is SBI customer care.",
      "timestamp": 1699999900
    },
    {
      "sender": "honeypot",
      "text": "Haan ji, kaun bol raha hai? Employee ID kya hai aapka?",
      "timestamp": 1699999950
    }
  ],
  "metadata": {
    "channel": "WhatsApp",
    "language": "English",
    "locale": "IN"
  }
}

Field Reference¶

Top-Level Fields¶

Field	Type	Required	Description
`sessionId`	`string`	Yes	Unique session identifier. Used for session persistence across requests.
`message`	`object`	Yes	The latest scammer message to respond to.
`conversationHistory`	`array`	No	Previous messages in this session (both scammer and honeypot). Defaults to `[]`.
`metadata`	`object`	Yes	Channel and language information.
`source`	`string`	No	Request source: `"guvi"` (default) or `"testing"`.

`message` Object¶

Field	Type	Required	Description
`sender`	`string`	Yes	Message sender. Any value accepted (e.g., `"scammer"`, `"user"`).
`text`	`string`	Yes	The message text content.
`timestamp`	`int \\| float \\| string`	Yes	When the message was sent. See Timestamp Handling.

`conversationHistory[]` Items¶

Same structure as message:

Field	Type	Required	Description
`sender`	`string`	Yes	`"scammer"`, `"honeypot"`, `"user"`, `"bot"`, etc.
`text`	`string`	Yes	Message text.
`timestamp`	`int \\| float \\| string`	Yes	Message timestamp.

The honeypot identifies its own previous messages by checking if sender is in {"honeypot", "bot", "agent", "assistant", "ai"}. All other sender values are treated as scammer messages for evidence extraction.

`metadata` Object¶

Field	Type	Required	Description
`channel`	`string`	Yes	Communication channel: `"SMS"`, `"WhatsApp"`, `"Email"`, etc.
`language`	`string`	Yes	Language preference: `"English"`, `"Hindi"`, `"Tamil"`, etc. Influences persona selection.
`locale`	`string`	Yes	Country locale: `"IN"` for India.

Timestamp Handling¶

The timestamp field is flexible and accepts multiple formats:

Format	Example	Handling
Unix seconds (int)	`1700000000`	Used as-is
Unix seconds (float)	`1700000000.123`	Used as-is
Unix seconds (string)	`"1700000000"`	Parsed to numeric
ISO 8601 string	`"2024-01-15T10:30:00Z"`	Converted to Unix timestamp

Timestamps must be non-negative. Invalid timestamps return a validation error.

Response Body¶

Success Response¶

{
  "status": "success",
  "reply": "Haan ji, par pehle aap apna employee ID batao beta. SMS mein toh SBI likha tha, aap kaun ho?",
  "sessionId": "session-abc-123",
  "scamDetected": true,
  "scamType": "KYC_BANKING",
  "confidenceLevel": 0.85,
  "extractedIntelligence": {
    "bankAccounts": [],
    "upiIds": [],
    "phishingLinks": [],
    "phoneNumbers": [],
    "emailAddresses": [],
    "suspiciousKeywords": ["KYC", "OTP", "account blocked"],
    "ifscCodes": [],
    "cryptoWallets": [],
    "aadhaarNumbers": [],
    "panNumbers": [],
    "amounts": [],
    "caseIds": [],
    "policyNumbers": [],
    "orderNumbers": []
  },
  "engagementMetrics": {
    "engagementDurationSeconds": 120.5,
    "totalMessagesExchanged": 3
  },
  "totalMessagesExchanged": 3,
  "engagementDurationSeconds": 120.5,
  "agentNotes": "Type: KYC_BANKING (85%) | Persona: sharma_uncle, Turn: 3 | Evidence: Keywords: KYC, OTP, account blocked"
}

Field Reference¶

Top-Level Response Fields¶

Field	Type	Description
`status`	`"success" \\| "error"`	Request processing status.
`reply`	`string`	The honeypot's persona-driven response to the scammer.
`sessionId`	`string \\| null`	Echoes back the request's session ID.
`scamDetected`	`boolean \\| null`	Whether a scam was detected in this conversation.
`scamType`	`string \\| null`	Classified scam type (see Scam Types).
`confidenceLevel`	`float \\| null`	Detection confidence between `0.0` and `1.0`.
`extractedIntelligence`	`object \\| null`	Evidence extracted from the conversation.
`engagementMetrics`	`object \\| null`	Duration and message count.
`totalMessagesExchanged`	`int \\| null`	Top-level message count (convenience duplicate).
`engagementDurationSeconds`	`float \\| null`	Top-level duration in seconds (convenience duplicate).
`agentNotes`	`string \\| null`	Human-readable summary of the analysis.

`extractedIntelligence` Object¶

All 14 fields are arrays of strings. Empty arrays indicate no evidence of that type was found.

Field	Description	Example
`bankAccounts`	Bank account numbers (9-18 digits)	`["50428123456"]`
`upiIds`	UPI IDs (`name@bank` format)	`["fraud@oksbi"]`
`phishingLinks`	Suspicious URLs (phishing keywords, shortened links, suspicious TLDs)	`["http://sbi-kyc-update.xyz"]`
`phoneNumbers`	Indian phone numbers (mobile and landline)	`["9876543210", "+91-8765432109"]`
`emailAddresses`	Email addresses	`["fake.sbi@gmail.com"]`
`suspiciousKeywords`	Scam indicator keywords	`["KYC", "OTP", "urgent"]`
`ifscCodes`	IFSC codes (`BANK0XXXXXX` format)	`["SBIN0001234"]`
`cryptoWallets`	Cryptocurrency wallet addresses (BTC, ETH, Tron)	`["0x1234...abcd"]`
`aadhaarNumbers`	Aadhaar numbers (12 digits, Verhoeff-validated)	`["234567890123"]`
`panNumbers`	PAN card numbers (`ABCDE1234F` format)	`["ABCPD1234F"]`
`amounts`	Monetary amounts (Rs, INR, rupees)	`["50000", "5000.50"]`
`caseIds`	FIR numbers, case references, complaint IDs	`["FIR-202512345", "CBI-2025-1234"]`
`policyNumbers`	Insurance/policy numbers	`["POL12345678"]`
`orderNumbers`	Order/tracking/shipment numbers	`["OD123456789"]`

`engagementMetrics` Object¶

Field	Type	Description
`engagementDurationSeconds`	`float`	Seconds since the session started.
`totalMessagesExchanged`	`int`	Total messages in the session (both sides).

Scam Types¶

The classifier assigns one of these scam types:

Type	Description
`KYC_BANKING`	KYC/banking verification scam
`DIGITAL_ARREST`	Fake police/CBI digital arrest intimidation
`JOB_SCAM`	Fake job or task-based earning scam
`SEXTORTION`	Blackmail/sextortion attempt
`LOTTERY_PRIZE`	Fake lottery or prize claim requiring fees
`TECH_SUPPORT`	Fake tech support remote access scam
`INVESTMENT_SCAM`	Fraudulent investment scheme
`INSURANCE_SCAM`	Fake insurance claim or policy scam
`ROMANCE_SCAM`	Romance/relationship-based fraud
`LOAN_SCAM`	Fake loan approval scam
`CUSTOM_DUTY`	Customs duty/parcel scam
`CRYPTO_INVESTMENT`	Cryptocurrency investment fraud
`UNKNOWN`	Could not classify with confidence
`NOT_SCAM`	Message does not appear to be a scam

Scam Detection Logic¶

scamDetected is computed from the classification, confidence, and evidence:

Classified scam type (any type except UNKNOWN and NOT_SCAM): always true
NOT_SCAM: true only if high-value evidence (UPI IDs or bank accounts) was extracted
UNKNOWN: true if confidence > 0.5, or UPI/bank evidence found, or 2+ suspicious keywords, or phone numbers detected

Example: Full Conversation Flow¶

Turn 1: Scammer initiates¶

// Request
{
  "sessionId": "demo-001",
  "message": {
    "sender": "scammer",
    "text": "Hello sir, this is from SBI. Your KYC has expired. Please update immediately or account will be blocked.",
    "timestamp": 1700000000
  },
  "conversationHistory": [],
  "metadata": { "channel": "SMS", "language": "English", "locale": "IN" }
}

// Response
{
  "status": "success",
  "reply": "Haan ji? KYC expire ho gaya? Par mera toh Dwarka branch hai... aap kaun bol rahe ho? Employee ID kya hai aapka?",
  "scamDetected": true,
  "scamType": "KYC_BANKING",
  "confidenceLevel": 0.75,
  "extractedIntelligence": {
    "suspiciousKeywords": ["KYC", "account blocked", "urgent"],
    "bankAccounts": [], "upiIds": [], "phoneNumbers": [],
    "phishingLinks": [], "emailAddresses": [],
    "ifscCodes": [], "cryptoWallets": [], "aadhaarNumbers": [],
    "panNumbers": [], "amounts": [], "caseIds": [],
    "policyNumbers": [], "orderNumbers": []
  },
  "engagementMetrics": {
    "engagementDurationSeconds": 0.5,
    "totalMessagesExchanged": 1
  }
}

Turn 3: Scammer shares payment details¶

// Request
{
  "sessionId": "demo-001",
  "message": {
    "sender": "scammer",
    "text": "Send verification fee of Rs. 500 to this UPI: sbikyc@oksbi",
    "timestamp": 1700000200
  },
  "conversationHistory": [ /* previous messages */ ],
  "metadata": { "channel": "SMS", "language": "English", "locale": "IN" }
}

// Response
{
  "status": "success",
  "reply": "500 rupaye? Achha... UPI se bhejun? Par pehle supervisor ka naam toh batao...",
  "scamDetected": true,
  "scamType": "KYC_BANKING",
  "confidenceLevel": 0.92,
  "extractedIntelligence": {
    "upiIds": ["sbikyc@oksbi"],
    "amounts": ["500"],
    "suspiciousKeywords": ["KYC", "account blocked", "urgent", "fee", "payment"],
    "bankAccounts": [], "phoneNumbers": [],
    "phishingLinks": [], "emailAddresses": [],
    "ifscCodes": [], "cryptoWallets": [], "aadhaarNumbers": [],
    "panNumbers": [], "caseIds": [],
    "policyNumbers": [], "orderNumbers": []
  },
  "engagementMetrics": {
    "engagementDurationSeconds": 200.0,
    "totalMessagesExchanged": 3
  }
}

API Request & Response¶

Endpoint¶

Request Headers¶

Request Body¶

Field Reference¶

Top-Level Fields¶

message Object¶

conversationHistory[] Items¶

metadata Object¶

Timestamp Handling¶

Response Body¶

Success Response¶

Field Reference¶

Top-Level Response Fields¶

extractedIntelligence Object¶

engagementMetrics Object¶

Scam Types¶

Scam Detection Logic¶

Example: Full Conversation Flow¶

Turn 1: Scammer initiates¶

Turn 3: Scammer shares payment details¶

`message` Object¶

`conversationHistory[]` Items¶

`metadata` Object¶

`extractedIntelligence` Object¶

`engagementMetrics` Object¶