Skip to main content
Contacts in Chatbase are records of your known, signed-in users (External ID, name, email, phone, Stripe accounts, and custom attributes) stored on an AI agent. They let your AI agent’s Actions work with the right customer’s data, such as looking up that customer’s Stripe subscription. Contacts are available on the Basic plan or higher and are managed from the Contacts page of each AI agent, through the Contacts API, or automatically through identity verification.

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.
Contacts belong to one AI agent, not to the whole workspace. The External ID is unique per AI agent, so the same person on two AI agents is two separate contacts.

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

No. Each AI agent has its own contacts. To use the same customer on two AI agents, create the contact on each one.
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.
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.
No. A user ID sent with the chat API only tags the conversation. Create contacts with the Contacts API or JWT identity verification.
They’re permanently deleted with it, along with the AI agent’s custom attributes. This can’t be undone.
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.