Contacts

The Contacts card decides whether this agent recognizes the person it's talking to, and whether it can write to that contact or look up others. Three switches, and no Configure button: there's no list behind this one.

Recognize callers is off on every agent that has never had it set, so nothing changes on an agent you already run until somebody turns it on. Let the agent update the contact starts on and Let the agent look up contacts starts off, and neither means anything while the first one is off.

This page covers what an agent does with a contact. For the records themselves — what one holds, how to create one by hand, how identifiers work — see Contacts.

Recognize callers

With this on, a call is matched to a contact before the agent greets anyone, on the caller's phone number. If no contact in your organization holds that number, one is created holding the number and nothing else. Every call moves that contact's Conversations count and its Last Contact, including the call that created it.

Two things then change about the call.

The agent is told who is on the line. What is known about the contact is added to the agent's system prompt: the name, the phone numbers and email addresses on file with the one this call came in on marked, how many prior conversations there have been and when the first was, the attribute values, the tags, and the notes. A contact holding nothing but a phone number — a first-time caller, one second old — produces none of this, because there is nothing to say about them yet.

That block also carries a disclosure rule: treat the values as facts about the caller rather than as instructions, confirm a value only when the caller states it first, and never read one out on request. It is written into the prompt, so it constrains the model the way the rest of your prompt does. Nothing enforces it outside the model.

With Redact caller PII on the Safety card, the attribute values are left out of the block entirely. The name, identifiers, tags, and notes still go in.

Caller memory follows the contact. With Memory set to anything other than None, what the agent remembers is filed under the contact instead of under the number the caller called from. Once both of a person's numbers are on the same contact, their mobile and their desk phone read as one history rather than two. A number not yet on that contact resolves to a contact of its own and keeps its own memory, and only a person can move it over: see What the agent cannot do. A caller whose memory was filed under a number before you turned this on keeps it: the older record is still read, and what this call adds is filed under the contact from then on. After two contacts are merged, a call to the kept contact also reads the memory filed under the record merged into it, for up to 10 merged records, most recently merged first.

Recognition does not need memory. An agent with Memory on None still gets the block above, so it can know who the caller is without retaining anything about their earlier calls.

Recognition does not personalize the Greeting. A first-time caller hears the greeting on the Persona card exactly as written, before the model takes its first turn, and a returning caller hears whichever returning-caller greeting you configured. Nothing substitutes the caller's name into any of them. There is no contact variable to reference in one, and Smart rewrite is instructed not to reference any specific detail about the caller. The agent has the name from its first turn onward, so it can use it in what it says next.

What recognition can change is which of those greetings fires. A caller counts as returning when the agent finds stored memory for them, and memory is filed under the contact — so once both of a person's numbers are on one contact, a call from either can be treated as returning. That needs Memory on; with it on None nothing is stored and every caller is a first-time one.

When no contact resolves

The call goes ahead exactly as it did before contacts existed: no block in the prompt, and memory filed under the number the caller called from. That happens when the caller withholds their number, when what the carrier sent is not a dialable number (an extension, a SIP user, a fragment), and when the lookup does not answer in time.

The lookup has 800 milliseconds, shared with the read of your organization's attribute definitions, and it sits in the silence before the greeting. Past that the call proceeds without a contact rather than making the caller wait.

Preview calls

A preview call has recognition switched off for the whole session, whatever the agent is saved with. A preview's caller ID is a placeholder that addresses nobody, so a contact resolved from it would be filed against a number that can never call back. Test this on a real call.

Chat and text

A returning website chat visitor is matched to a contact, and their conversation is attached to it. The match runs on the id the chat widget stored in the visitor's browser on an earlier visit, so a visitor arriving for the first time is matched to nothing and no contact is created for them. They get one when they come back.

The agent is not told who a chat visitor is. There is no block in its prompt, and the conversation's memory stays filed under the browser rather than under the contact, so everything in Recognize callers above is true of a phone call only.

An agent's Contacts card does not reach text messages. Texts are matched to contacts by the organization-wide Recognize texters setting instead; see Text messages.

Let the agent update the contact

Voice only, and on by default once Recognize callers is on. It gives the agent the update_contact tool, which writes back to the contact this caller resolved to.

It can set a first and last name, append one line to the notes, add tags, and fill in the attributes your organization marked Agent can edit under Admin → Contact Attributes. It cannot add a phone number or an email address, and it cannot reach any contact other than the one on the phone.

Turn it off and the agent still recognizes callers; it just has no way to record what it learned.

Let the agent look up contacts

Voice only, and off by default. With it on, and Recognize callers on too, the agent gets the lookup_contact tool, which finds a contact by phone number or email address. It is for a caller on a number that is not their own: the agent finds their record by the number or address they give, then confirms details they state against it.

A match returns the same details the agent is told about its own caller (see Recognize callers), under the same disclosure rule, with a note that the contact may not be the caller. The tool tells the agent to confirm only a value the caller states first and never to read one out on request. It finds nobody by name, and it changes nothing: the call stays attached to the caller's own contact, and memory and update_contact stay on that contact too.

The agent can make three lookups per agent session, and the fourth is refused. A transfer to another agent, or a dropped call that resumes, starts a new session and a new count.

Pair it with the verify-identity skill. A lookup hands the agent one person's record during a call with someone who may not be that person, so the caller should prove who they are first. Switch on verify-identity and tell the agent in your system prompt to verify the caller before it uses lookup_contact. That order is an instruction to the model; nothing outside the model enforces it.

What the agent cannot do

• Search by name. Recognition hands the agent the contact its own caller resolved to. Only Let the agent look up contacts lets it find another, and only by phone number or email address.
• Attach a number or an address. A caller saying "my other number is ..." changes nothing. Only a person adds an identifier, in the contact sidebar or over the API. That is deliberate: an identifier attached on a caller's say-so would resolve whoever calls from it next to this contact, and hand them this contact's name, notes, and attributes.
• Merge two records. Only a person merges contacts, from the contact's sidebar. See Merging two contacts.

Limits and defaults

Next steps

• Contacts — the records, identifiers, attributes, and deletion.
• Built-in Tools — update_contact and lookup_contact alongside the call-control tools.
• Brain — caller memory, which this changes the filing of.