Skip to main content
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.
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.

​
What is stored

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 - 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

The API

Set all fields for one caller in a single request, or import up to 1,000 callers at a time.

The pre-call gate

Answer with a caller object while the phone is still ringing. Nothing is stored - your own system stays the source of truth.

The engine

After every call, details the caller stated are saved automatically. No setup.

​
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 and Data retention.