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

# Caller context

> What your agent already knows about the person on the line

Caller context is a small record of what your agent knows about a caller before the conversation starts - their name, email, location, a reference number. The agent uses it instead of asking again, and confirms each detail before acting on it.

It fills two gaps at once: speech recognition is at its worst on emails and reference numbers, and callers dislike repeating themselves.

<Note>
  Caller context describes **the people your number talks to**, not your own numbers. You set it per caller, under the number they use to reach you.
</Note>

## What is stored

| Field          | Set by you | Set by the engine                                                                    |
| -------------- | ---------- | ------------------------------------------------------------------------------------ |
| `name`         | Yes        | Yes, when the caller states a full name                                              |
| `email`        | Yes        | Yes, when the caller states one                                                      |
| `phone`        | Yes        | Yes, when the caller gives a contact number other than the one they are calling from |
| `location`     | Yes        | Yes, when the caller states one                                                      |
| `reference_id` | Yes        | Yes, when the caller gives an account, order or booking reference                    |
| `preference`   | Yes        | Yes, when the caller states one explicitly                                           |
| `last_call`    | No         | What the caller wanted on their previous call - never what happened                  |
| `open_item`    | No         | Something still pending for the caller after a call                                  |

`last_call` and `open_item` are written by the engine only. Sending them through the API returns `engine_only_field`.

## One record per number, per caller

A record belongs to **one of your phone numbers and one caller number**. The same person calling two of your numbers has two separate records.

This is deliberate. One agent can serve many separate businesses, each on its own number - so a customer known to one business is a stranger to the next, and their details never cross. If a business has two numbers, import its customers to each number separately.

## Who wins

There is one value per field, and the last write wins:

* You set an email through the API. The agent uses it.
* On a call the caller confirms a different email. The engine stores the new one, and the next call uses it.
* You set it again through the API. Yours is now the current value.

An empty value never overwrites a stored one, so a wrong number or a silent call cannot erase what you already had. Only an explicit `null` through the API removes a field.

## How the agent uses it

The record is placed in the agent's instructions as a `## CALLER CONTEXT` block with six rules:

1. Use known details naturally. Do not ask the caller to repeat information already known.
2. Use the stored name naturally. If the caller gives a different name, use the new name for this call.
3. Before using exact details for an action, verify them with the caller.
4. If the caller gives a different value, use the new value for this call.
5. Previous requests, preferences and open items are context only. Determine what the caller needs NOW.
6. Never assume an action happened from this context. Only confirm actions actually performed or verified by the appropriate tool.

In practice, a booking sounds like this:

> *Agent:* "Shall I book this under Sam Carter, sam.carter at example dot com?"
>
> *Caller:* "Yes, that's right."

The agent will not call a booking, reschedule or cancel tool until the caller has confirmed the details in that call. A detail already on file is said out loud, not spelled - it was confirmed when it was saved. A **new** value the caller gives is read back letter by letter before it is used.

## Where it applies

Caller context is used on inbound calls, outbound calls, the opening greeting, and the [SMS agent](/sms/sms-agent) - all from the same record.

On outbound calls the roles are simply reversed: your number is the business number, the number you dial is the caller.

## Three ways to fill it

<CardGroup cols={3}>
  <Card title="The API" icon="code" href="/api-reference/caller-context/set">
    Set all fields for one caller in a single request, or import up to 1,000 callers at a time.
  </Card>

  <Card title="The pre-call gate" icon="bolt" href="/advanced/precall-gate">
    Answer with a `caller` object while the phone is still ringing. Nothing is stored - your own system stays the source of truth.
  </Card>

  <Card title="The engine" icon="microphone" href="/advanced/post-call-analysis">
    After every call, details the caller stated are saved automatically. No setup.
  </Card>
</CardGroup>

## Removing a caller

`DELETE /v1/phone-numbers/{number}/callers/{caller}` erases the whole record - both what you set and what the engine learned. See [Delete caller context](/api-reference/caller-context/delete) and [Data retention](/concepts/data-retention).

## Related

* [Set caller context](/api-reference/caller-context/set) - the API reference
* [Pre-call gate](/advanced/precall-gate) - supply details live, per call
* [Cal.com booking](/actions/calcom) and [Google Calendar](/actions/google-calendar) - how details are confirmed before a booking