Webhooks

Spam Rejection

Screen inbound calls before an agent ever picks up. Block known bad numbers, apply carrier spam scores, and make your own accept-or-reject decision from your server.

How screening works

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Customer   │────▶│   Phone or  │────▶│   Katexs    │
│  Calls or   │     │    Chat     │     │    Agent    │
│  Messages   │     │   Widget    │     │  (AI Brain) │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                               │
                    ┌──────────────────────────┼──────────────────────────┐
                    ▼                          ▼                          ▼
              ┌─────────┐              ┌─────────┐                 ┌─────────┐
              │ Calendar│              │   CRM   │                 │ Transfer│
              │  Book   │              │  Push   │                 │  Human  │
              └─────────┘              └─────────┘                 └─────────┘

Every inbound call passes through three gates in order: your block list, the carrier spam score, then an optional call.inbound webhook where your server has the final say. The first gate that rejects ends the call before any billable agent time.

Built-in filters

Filter	Setting	Behavior
Block list	Settings → Phone Numbers → Blocked	Exact numbers or prefixes are rejected silently.
Spam score	reject_above: 0–100	Carrier-reported likelihood. 80 is a sensible starting threshold.
Anonymous callers	reject_anonymous: true	Rejects withheld or unavailable caller ID.
Rate limiting	max_calls_per_number_per_hour	Throttles repeat dialers from the same number.
Geography	allowed_country_codes	Accepts only listed country codes.

json

{
  "spam_rejection": {
    "enabled": true,
    "reject_above": 80,
    "reject_anonymous": true,
    "allowed_country_codes": ["+1"],
    "max_calls_per_number_per_hour": 5,
    "action": "reject"
  }
}

Rejection actions

reject — Carrier-level rejection. The caller hears a fast busy. Costs nothing.
voicemail — Routes straight to voicemail without engaging the agent. Safer for false positives.
tag_only — Lets the call through but marks it spam_suspected in Call Logs. Use this while tuning.

Deciding on your server

Subscribe to call.inbound and Katexs will wait up to 1.5 seconds for your response before connecting. This is where you check your own CRM, fraud tooling, or customer list.

json

// Katexs sends
{
  "type": "call.inbound",
  "data": {
    "from": "+15555550142",
    "to": "+15555550100",
    "spam_score": 62,
    "is_anonymous": false
  }
}

// You respond
{
  "action": "accept",
  "agent_id": "agt_vip",
  "variables": { "first_name": "Maria", "tier": "scale" }
}

Return action: "reject" to drop the call, or action: "accept" with an optional agent_id to route known customers to a different agent than cold callers.

If your endpoint times out, the call is accepted by default — screening should never cost you a real customer. Change this with on_timeout: "reject" only if you are confident in your uptime.

Tuning without losing calls

1
Start in tag_only
Run for a week and review everything flagged in Call Logs.
2
Find your threshold
Look at where real customers stop appearing in the flagged set — usually somewhere between 70 and 85.
3
Switch to voicemail
A false positive lands in voicemail instead of disappearing.
4
Move to reject
Only once the flagged set is clean for a full week.