Skip to main content
Caller context means a returning caller never has to spell their email again. Before the conversation starts, the agent is given what is on file for that person - name, email, phone, location, reference, preference - and uses it instead of asking. It confirms each detail out loud before acting on it. It closes 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 numbers talk to, not your own numbers. Each record belongs to one caller on one of your numbers.

​
What does the agent already know about a caller?

Up to eight details, and nothing else. Six you can set yourself; two only the engine writes. The agent is never told what happened on a previous call - no bookings, no outcomes, no summaries. last_call and open_item are engine-only. Sending them through the API returns engine_only_field. last_call is stored and returned by the API and your webhook, but it is not shown to the agent during a call. Even phrased as intent it read to the agent like something already done - the one thing caller context must never imply.

​
Does the agent remember callers between calls?

Yes, automatically, with no setup. After every call the engine saves any details the caller stated about themselves, and the next call to that number starts with them. Nothing is remembered about what was discussed or decided - only who the person is.

​
Can I turn caller memory off?

No. There is no setting today that stops the engine storing or using caller context. Greet by name on the agent only stops the greeting using the name; the details are still given to the agent for the rest of the call. What you can control:
  • Delete a record - DELETE /v1/phone-numbers/{number}/callers/{caller} erases everything stored for that caller, both what you set and what the engine learned.
  • Keep your own source of truth - answer the pre-call gate with a caller object. Those details are used for that call and never stored.
  • Retention - everything is deleted with the rest of the call data after 90 days. See Data retention.
A switch to disable it is planned. Until then, assume any detail a caller states on a call is remembered for their next call to that number.

​
Why does the same person have two records?

Because a record belongs to one of your numbers and one caller number. The same person calling two of your numbers has two separate records, and they never cross. This is deliberate. One agent can serve hundreds of separate businesses, each on its own number - so a customer known to one business must be a stranger to the next. If one business has two numbers, import its customers to each number separately.

​
What happens if the caller gives a different name?

The new value wins for that call and is stored for the next one. There is one value per field and the last write wins, whether the write came from you or from the conversation.
  1. You set an email through the API. The agent uses it.
  2. On a call the caller confirms a different email. The engine stores the new one, and the next call uses it.
  3. You set it again through the API. Yours is 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 does the agent use it during a call?

The record is added to the agent’s instructions as a ## CALLER CONTEXT block, placed at the very end - nearest the conversation. Position matters: at the top of a long prompt it lost to closer instructions and the agent told a known caller it had no details on file. The block carries 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 does it apply?

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 every field 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 system stays the source of truth.

The engine

After every call, details the caller stated are saved automatically. No setup.
Setting one caller through the API:
The first number is yours, the second is the caller’s. Send null for a field to remove it. For more than one caller at a time, use the import endpoint - up to 1,000 per request.