Callers: who called your agent, and blocking them

A caller is one person as one of your agents sees them, across all their calls. Callers are made as people call, never by hand:

Web callers (the share link and the website widget) are told apart by their Google sign-in, or else by a random id their browser keeps.
App callers by their Wixzel Voice account.
Phone callers by their number.

The same person calling two of your agents is two callers.

What a caller record holds

{
  "id": "6717f0c2a1b2c3d4e5f60718",
  "object": "caller",
  "agent_id": "6717e9a0a1b2c3d4e5f60001",
  "kind": "web",
  "name": "Priya Nair",
  "email": "priya@example.com",
  "phone": null,
  "verified_by": "google",
  "location": { "city": "Kochi", "region": "Kerala", "country": "IN" },
  "platform": { "source": "website", "browser": "Chrome", "os": "Android 14", "device": "mobile" },
  "page_url": "https://example.com/pricing",
  "call_count": 3,
  "blocked": false,
  "blocked_at": null,
  "first_seen_at": "2026-10-19T08:12:44.000Z",
  "last_seen_at": "2026-10-21T10:02:13.000Z"
}

Field	What it is
`kind`	`web`, `app` or `phone`
`name`, `email`, `phone`	What the caller gave, or what their sign-in said. Null when unknown
`verified_by`	`google` (a Google sign-in), `app` (their Wixzel account in the app), `form` (typed in, not checked), or null
`location`	Approximate, from their IP address, where they last called from. The address is kept only as a hash. Null for phone calls
`platform.source`	`share_link`, `website`, `app` or `phone`
`platform.browser`, `os`, `device`	From the User-Agent. `device` is `mobile`, `tablet` or `desktop`
`page_url`	The page a website widget call was made from
`call_count`	How many calls they made to this agent
`blocked`, `blocked_at`	Whether they are blocked now, and since when

What a web caller must give before a call is set per agent with sharing.caller_info. See Mascots.

List callers

curl "https://api.voice.wixzel.com/v1/callers?agent_id=AGENT_ID&limit=20" \
  -H "Authorization: Bearer $WIXZEL_API_KEY"

Query	What it does
`agent_id`	Only this agent’s callers
`blocked`	`true` for the blocklist, `false` for everyone else
`limit`, `starting_after`, `ending_before`	Pagination

Needs calls:read.

Retrieve a caller

curl https://api.voice.wixzel.com/v1/callers/CALLER_ID \
  -H "Authorization: Bearer $WIXZEL_API_KEY"

Needs calls:read.

Block or unblock a caller

curl -X PATCH https://api.voice.wixzel.com/v1/callers/CALLER_ID \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "blocked": true }'

A blocked caller cannot call that agent again: not from its share link, its website widget, the app or by phone. The share page and the widget answer them with 403 caller_blocked. Send "blocked": false to unblock. Needs calls:write.

The caller on a call

Every call has a caller field: who was on it, as they were at the time. It is null when nothing is known.

{
  "id": "6718a1...",
  "object": "call",
  "channel": "web",
  "from": "Priya Nair",
  "caller": {
    "id": "6717f0c2a1b2c3d4e5f60718",
    "name": "Priya Nair",
    "email": "priya@example.com",
    "phone": null,
    "verified_by": "google",
    "location": { "city": "Kochi", "region": "Kerala", "country": "IN" },
    "platform": { "source": "website", "browser": "Chrome", "os": "Android 14", "device": "mobile" },
    "page_url": "https://example.com/pricing",
    "blocked": false
  }
}

A web call’s from is the caller’s name or contact when known. caller.id is the caller record, and caller.blocked says whether they are blocked now. To list one caller’s calls, filter by caller_id:

curl "https://api.voice.wixzel.com/v1/calls?caller_id=CALLER_ID" \
  -H "Authorization: Bearer $WIXZEL_API_KEY"

Getting started

Guides

Carriers

Concepts

API reference

Callers: who called your agent, and blocking them

What a caller record holds

List callers

Retrieve a caller

Block or unblock a caller

The caller on a call

​What a caller record holds

​List callers

​Retrieve a caller

​Block or unblock a caller

​The caller on a call

What a caller record holds

List callers

Retrieve a caller

Block or unblock a caller

The caller on a call