Contacts overview
Contacts are durable records of the people your agents talk to — name, email, phone, linked Stripe accounts, and your own custom attributes — scoped per agent and keyed by a stable external ID. Search, sort, edit, and manage them from the dashboard or the API.
View as MarkdownContacts are durable records of the people your agents interact with. Where a conversation is a single exchange, a contact is the person behind it — a profile you can recognize across conversations, enrich with your own data, and look up from the dashboard or the API.
Each contact carries core profile fields, optional linked Stripe accounts, and any custom attributes you define. Together they give your agent and your team context: who this customer is, what plan they're on, what their order history is — whatever you choose to store.
A contact belongs to one agent (its "chatbot"). The same person talking to two of your agents is two separate contact records — which keeps each agent's contact list clean and scoped to who it actually serves.
What a contact holds
| Field | Description |
|---|---|
| External ID | A stable, caller-supplied identifier, unique per agent. This is how you reference a contact and how upserts match — typically your own user ID, customer ID, or email. |
| Name | The contact's display name. |
| The contact's email address. | |
| Phone number | The contact's phone number. |
| Stripe accounts | One or more linked Stripe accounts (label, Stripe ID, Stripe email) for billing context. |
| Custom attributes | Your own typed fields — plan tier, lifetime value, signup date, VIP flag, and so on. See Custom attributes. |
| Created / updated | Timestamps maintained automatically. |
The external ID is the key everything hangs off — it must be unique per agent and shouldn't change. Use your own customer ID or user ID. If you only have email, email works, but a permanent internal ID is more robust.
Why contacts matter
- Recognize returning customers — tie conversations to a known person rather than treating every chat as anonymous.
- Give the agent context — custom attributes (plan, status, order history) let the agent and your team personalize responses.
- Power your help desk — when a conversation escalates, your team sees who they're talking to in the Help Desk.
- Sync with your systems — push contacts in from your app or store via the Contacts API, and keep them current.
Managing contacts in the dashboard
Each agent has a Contacts tab with a searchable, sortable, paginated table. From it you can:
- Search across contacts and sort by any column.
- Choose columns — show or hide core fields and any of your non-archived custom attributes.
- Add or edit a contact with typed inputs that match each attribute's type.
- Import contacts in bulk from CSV or JSON.
- Manage attributes — define, archive, and restore the custom fields on this agent.
- Adjust rows per page to scan large lists efficiently.
Creating and updating contacts
Add contacts three ways:
- 1ManuallyUse Add on the Contacts tab and fill in the fields, including typed inputs for any custom attributes.
- 2In bulkImport a CSV or JSON file. See Importing contacts.
- 3Via the APICreate or upsert contacts programmatically from your own app or store. See the Contacts API.
Creating a contact whose external ID already exists for that agent updates the existing record rather than duplicating it. This makes imports and API syncs safe to re-run — the external ID is the match key.
Stripe accounts
A contact can carry one or more linked Stripe accounts, each with a label, Stripe ID, and Stripe email. This gives your team billing context right alongside the contact — useful when a conversation turns into a billing or subscription question.
Contacts and the API
The dashboard and the public API operate on the same contacts. Programmatic access uses your API key and is scoped to the agent (chatbot) the key belongs to — you can create, list, update, and delete contacts and manage custom attributes. See the Contacts API reference for endpoints, payloads, and authentication.
Included on every plan. Contacts aren't gated behind a higher tier — they're part of Bookbag out of the box.