> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voice.wixzel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Callers: who called your agent, and blocking them

> A caller is one person as one agent sees them, across all their calls. List them, look one up, and block or unblock 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

```json theme={null}
{
  "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](/mascots.md#who-can-call).

## List callers

```bash theme={null}
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](/pagination.md) |

Needs `calls:read`.

## Retrieve a caller

```bash theme={null}
curl https://api.voice.wixzel.com/v1/callers/CALLER_ID \
  -H "Authorization: Bearer $WIXZEL_API_KEY"
```

Needs `calls:read`.

## Block or unblock a caller

```bash theme={null}
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.

```json theme={null}
{
  "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`:

```bash theme={null}
curl "https://api.voice.wixzel.com/v1/calls?caller_id=CALLER_ID" \
  -H "Authorization: Bearer $WIXZEL_API_KEY"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.