Contacts
Store and manage identified people, typed attributes, and mapped CSV or XLSX imports for your agent.
A Contact is an identified person who has chatted with your agent — as opposed to an anonymous visitor. Each Contact is keyed by an immutable External ID that comes from your own system, so the same person stays a single Contact across sessions and devices.
Find your contacts under your agent's Contacts tab.
What a Contact Stores
| Field | Description |
|---|---|
| External ID | The immutable id from your system (the JWT sub). Unique per agent. |
| The contact's email address. | |
| Name | The contact's display name. |
| Phone | The contact's phone number. |
| Custom attributes | Any extra data you attach (plan, company, Stripe ids, …). |
| Last seen | Automatically updated each time the contact chats. |
Contact data is stored for you to view and segment. For privacy, it is never injected into the agent's answers — see Identity Verification → Privacy.
How Contacts Are Created
Automatically, from identity verification (recommended)
When you enable identity verification, your backend signs a JWT for each logged-in user. The first time a verified user chats, Agentkit creates a Contact from the token's claims and links the conversation to it. Later chats update the same Contact and refresh Last seen. No separate API call is needed.
Manually
Click Add contact, then enter an External ID (required) plus optional name, email, and phone. The External ID must be unique for the agent.
By file import
Use Import to bulk-create or update contacts from a spreadsheet — see below.
Defining custom attributes
Open Attributes to add typed fields for the agent's contacts. Each field has an immutable key, an editable label, and one of four types: text, number, boolean, or date. Archiving a field hides it without deleting values already stored on contacts.
Agentkit reserves instagram_username, stripe_customer_id, and source for integrations. They appear as read-only system fields. Other undeclared values from verified identity tokens remain stored even though they do not appear as editable fields.
Importing contacts
Click Import and upload a .csv or .xlsx file. The first row must contain headers. The five steps let you map source columns, preview normalized values and row errors, choose duplicate behavior, import, and retry failures.
| Column | Required | Notes |
|---|---|---|
external_id | Yes | Unique id per contact. Rows without it are skipped. |
name | No | Up to 255 characters. |
email | No | Up to 320 characters. |
phone | No | Up to 50 characters. |
external_id,name,email,phone import-001,Alice Imported,[email protected],+1 555 000 0001 import-002,Bob Imported,[email protected],+1 555 000 0002
Source headers do not need to match these names. Map one column to External ID, then optionally map name, email, phone, and active custom attributes. Use Download template for a starter CSV.
Limits and behavior:
- Max file size 5 MB; up to 10,000 rows per import.
- Choose whether repeated External IDs in the file keep the last row or skip every duplicate. The default is skip.
- Choose whether existing contacts are updated or skipped. The default is update.
- Blank mapped cells preserve existing values during dashboard imports.
- Number, boolean, and date fields are normalized in Preview before anything is written.
- If individual rows fail, download only those rows as CSV or retry them from Results.
Finding Contacts
The Contacts table supports:
- Search across External ID, email, name, and phone.
- Pagination for large contact lists.
- A Columns toggle to show or hide columns.
- Optional columns for active custom attributes.
- An edit action for profile fields and typed attributes.