> ## Documentation Index
> Fetch the complete documentation index at: https://chatbase.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Contacts: personalize your AI agent for known users

> Learn how to use contacts to enable personalized, secure interactions between your users and AI agents.

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](https://chatbase.co/docs/user-guides/chatbot/actions/stripe-action.md) 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.

> [!NOTE]
>
> 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](https://chatbase.co/docs/api-reference/v1/contacts/create-contacts-for-a-chatbot.md) or manage them through the dashboard.

> [!NOTE]
>
> **Recommended:** Use [JWT identity verification](https://chatbase.co/docs/developer-guides/website-integration/identity-verification.md#method-1-jwt-recommended) 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](https://chatbase.co/docs/developer-guides/website-integration/identity-verification.md) to securely link them to their contact data.

> [!NOTE]
>
> 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).

### 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:

| Data | Who uses it | How |
| - | - | - |
| Metadata sent when you identify the user (for example, `name` in `window.chatbase("identify", ...)`) | The AI agent, in its replies | Added as hidden context, up to 1,000 characters |
| The stored contact: name, email, phone, custom attributes, and Stripe accounts | [Actions](https://chatbase.co/docs/user-guides/chatbot/actions/stripe-action.md) | Read as `{contact.*}` variables |

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

| Source | Creates or updates a contact? |
| - | - |
| [JWT identity verification](https://chatbase.co/docs/developer-guides/website-integration/identity-verification.md#method-1-jwt-recommended) in the Chat Bubble, and the mobile SDK | Yes, by `user_id` |
| [Contacts API](https://chatbase.co/docs/api-reference/v1/contacts/create-contacts-for-a-chatbot.md), **Add contact**, and [Import](https://chatbase.co/docs/user-guides/chatbot/contacts/uploading-contacts.md) | Yes |
| WhatsApp Business app contact sync | Yes |
| A user or contact ID sent with the chat API | No. It only tags the conversation. |
| **Chat as user** in the Playground | No. It uses a temporary contact that isn't saved. |
| People who message you on WhatsApp and other channels | No. They're matched to an existing contact by phone number when one exists. |

## 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](https://chatbase.co/docs/user-guides/chatbot/activity.md). 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](https://chatbase.co/docs/user-guides/chatbot/contacts/uploading-contacts.md).
* **API:** up to 1,000 contacts per create request.

## Key Benefits

> [card] Access-controlled data
>
> Only workspace members whose role allows access to contacts can view or change them.

> [card] Personalized conversations
>
> AI agents can reference user-specific information to provide tailored responses.

> [card] Actions integration
>
> Contact data powers Actions, enabling AI agents to perform user-specific operations such as [Stripe Actions](https://chatbase.co/docs/user-guides/chatbot/actions/stripe-action.md).

> [card] Data synchronization
>
> Keep Chatbase contacts in sync with your external systems and databases.

## Frequently asked questions

> [accordion] Are contacts shared across all AI agents in my workspace?
>
> No. Each AI agent has its own contacts. To use the same customer on two AI agents, create the contact on each one.

> [accordion] 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](https://chatbase.co/docs/api-reference/v1/contacts/create-contacts-for-a-chatbot.md). See [Uploading Contacts](https://chatbase.co/docs/user-guides/chatbot/contacts/uploading-contacts.md).

> [accordion] 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](https://chatbase.co/docs/developer-guides/website-integration/identity-verification.md).

> [accordion] 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](https://chatbase.co/docs/api-reference/v1/contacts/create-contacts-for-a-chatbot.md) or JWT identity verification.

> [accordion] 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.

> [accordion] Which plans include Contacts?
>
> Basic or higher. There's no limit on the number of contacts.

## Next Steps

> [card] [Uploading Contacts](https://chatbase.co/docs/user-guides/chatbot/contacts/uploading-contacts.md)
>
> Import contacts in bulk, update them by External ID, and bring in custom attributes.

> [card] [Identity Verification](https://chatbase.co/docs/developer-guides/website-integration/identity-verification.md)
>
> Implement secure user identification to link sessions with contact data.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.