How Contacts Work
Contacts bridge the gap between anonymous visitors and identified users in your system. When users interact with your AI agent, you can link their session to stored contact data to provide personalized experiences.Unlike anonymous visitors, contacts represent users who are authenticated and identified within your business system.
The Identification Process
1
Create contacts
Upload user data to Chatbase using the Contacts API or manage them through the dashboard.
Recommended: Use JWT identity verification to automatically create and update contacts when users interact with your AI agent. This eliminates the need for separate API calls.
2
Verify user identity
When users interact with your AI agent, use identity verification to securely link them to their contact data.
The
user_id from your verification must match the external_id of a contact for the data to be accessible.3
Enable personalized interactions
Once linked, your Actions can use the contact’s stored data as
{contact.*} variables to perform operations on behalf of the user. To give the AI agent itself context for its replies, send metadata with the user’s identity. See What the AI agent sees.What the AI agent sees
The fields stored on a contact aren’t added to the AI agent’s prompt. They’re used in two different ways:
For example, if Jane Doe (External ID
user-001) is identified with the metadata plan: Pro, the AI agent can mention her Pro plan in a reply, and a Stripe Action can use her stored Stripe account to look up her invoices.
What creates a contact
The Contacts page
Open an AI agent and click Contacts in the sidebar. The page shows how many contacts the AI agent has, with three buttons: Manage attributes, Import, and Add contact. The table has a Search box and the columns Id, External ID, Email, Name, Stripe Accounts, Phone Number, plus one column per custom attribute. Each row has edit and delete controls, and selecting rows lets you delete them in bulk. When the AI agent has no contacts yet, the table reads “No contacts found. You can start adding contacts through our API.” To find a contact’s conversations, go to Activity. A conversation with a known user shows their email or user ID in its details, with Open contact and Filter chats by this contact.Plans and limits
- Plans: Contacts are available on the Basic plan or higher. Without it, the Contacts page shows an upgrade card.
- Number of contacts: there’s no limit on how many contacts an AI agent can have.
- Import: up to 1,000 rows and 5 MB per file. See Uploading Contacts.
- API: up to 1,000 contacts per create request.
Key Benefits
Access-controlled data
Only workspace members whose role allows access to contacts can view or change them.
Personalized conversations
AI agents can reference user-specific information to provide tailored responses.
Actions integration
Contact data powers Actions, enabling AI agents to perform user-specific operations such as Stripe Actions.
Data synchronization
Keep Chatbase contacts in sync with your external systems and databases.
Frequently asked questions
Can I import contacts?
Can I import contacts?
Yes. Click Import on the Contacts page to upload a
.csv or .xlsx file of up to 1,000 rows and 5 MB, or add contacts from your own code with the Contacts API. See Uploading Contacts.Does the AI agent automatically see a contact's details?
Does the AI agent automatically see a contact's details?
No. Stored contact fields are available to Actions as
{contact.*} variables. For the AI agent to use details in its replies, send them as metadata when you identify the user.Does chatting through the API create a contact?
Does chatting through the API create a contact?
No. A user ID sent with the chat API only tags the conversation. Create contacts with the Contacts API or JWT identity verification.
What happens to contacts when I delete the AI agent?
What happens to contacts when I delete the AI agent?
They’re permanently deleted with it, along with the AI agent’s custom attributes. This can’t be undone.
Which plans include Contacts?
Which plans include Contacts?
Basic or higher. There’s no limit on the number of contacts.
Next Steps
Uploading Contacts
Import contacts in bulk, update them by External ID, and bring in custom attributes.
Identity Verification
Implement secure user identification to link sessions with contact data.