Identifying your customers
Send your customers' name, company and attributes like their plan from your website, your React app or your backend, so your team and your agent know who they're helping
Your product already knows who your customers are: their plan, their company, when they signed up, how many seats they pay for. Send that to FutureBase and it shows on the customer's page under Customers and next to their conversation in Live Desk, so nobody has to ask "which plan are you on?" again.
There are three ways to send it:
- The chat bubble's script tag, with a few
data-futurebase-user-*attributes - The React package, with the
userprop onChatProvider - The Customers API, from your backend, for customers who haven't opened the chat yet or for data that changes away from your website
All three update the same customer. You can see the code for your agent, with your own attribute names, under Customers → Settings → Send from your app.
What you can send
A customer's profile has a few fixed fields and any number of attributes:
| Field | What it is |
|---|---|
name | Their full name |
phone | Their phone number |
company | Their company's name |
avatarUrl | A picture of them, as an https URL |
attributes | Anything else, as an object: { "plan": "pro", "mrr": 49, "beta": true } |
Attributes follow a few rules:
- Keys use lowercase letters, digits and underscores, start with a letter and are up to 64 characters:
plan,signed_up_at,seats. The keysname,email,phone,companyandavatarare reserved. - Values are text (up to 1,000 characters), numbers or
true/false. Send dates as ISO strings like"2026-03-02"or"2026-03-02T10:00:00Z". nullremoves an attribute.- A customer keeps up to 50 attributes, and an agent up to 100 different keys. From the chat bubble, the whole profile can be up to 8 KB.
The first value FutureBase sees for a key sets its type: text, number, yes/no or date. Later values must fit that type. You can rename an attribute or change its type under Customers → Settings → Attributes.
From the chat bubble
Add the profile to the script tag for signed-in customers. Attributes are one JSON object, in single quotes so the double quotes inside stay valid HTML:
<script src="https://embed.futurebase.io/widget.js" data-wid="YOUR_WEBSITE_ID"
data-futurebase-user-email="[email protected]"
data-futurebase-user-hash="THE_HASH_FROM_YOUR_SERVER"
data-futurebase-user-name="Dana Ruiz"
data-futurebase-user-phone="+34 612 400 118"
data-futurebase-user-company="Northwind"
data-futurebase-user-avatar="https://northwind.io/avatars/dana.png"
data-futurebase-user-attributes='{"plan":"pro","mrr":49,"signed_up_at":"2026-03-02"}'
defer></script>If you change these attributes later, for example after the customer upgrades in a single-page app, an open chat picks up the new values. The profile goes to the chat inside the page, never in a URL. Attributes that aren't valid JSON are ignored.
data-futurebase-user-email and data-futurebase-user-hash come from the identity check. Without them the profile still works, but only until the customer is verified, see Who can change a customer.
From React
Pass the same fields on the user prop of ChatProvider:
import { ChatBubble, ChatProvider } from "@futurebase/chat/react";
<ChatProvider
wid="YOUR_WEBSITE_ID"
user={{
email: user.email,
hash: userHash,
name: user.name,
phone: user.phone,
company: user.companyName,
avatarUrl: user.avatarUrl,
attributes: { plan: user.plan, mrr: user.mrr, signed_up_at: user.createdAt },
}}
>
{children}
<ChatBubble />
</ChatProvider>When the user prop changes, an open chat picks up the new profile.
name, phone, company, avatarUrl and attributes need the next release of
@futurebase/chat (0.2). Older versions ignore them.
From your backend
The Customers API creates or updates customers from your server: when someone signs up, upgrades or cancels, or in a nightly sync. It is on the Standard plan and up.
Get a token
Open Customers → Settings → API tokens and create a token with Create, update and delete customers (contacts:write) and, if you also read customers back, Read customers (contacts:read). Only organization admins and owners can create these tokens. Copy the token right away: it's shown only once.
Keep the token on your server, for example as FUTUREBASE_API_TOKEN. It acts as you, so treat it like a password. Tokens last a year; revoke one on the same page.
Every call sends it as a bearer token: Authorization: Bearer fbx_…. Your agent's ID is the data-wid from your install snippet.
Create or update a customer
curl -X POST https://api.futurebase.io/v1/contacts \
-H "Authorization: Bearer $FUTUREBASE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"agentId": "YOUR_AGENT_ID",
"externalId": "usr_8f2a",
"email": "[email protected]",
"name": "Dana Ruiz",
"company": "Northwind",
"attributes": { "plan": "pro", "mrr": 49, "signed_up_at": "2026-03-02" },
"tags": { "add": ["vip"] }
}'FutureBase finds the customer by externalId (your user ID), then by email (only a customer without another user ID), and creates one if neither matches. Send at least one of the two. The answer is 201 with { "contact": …, "created": true } for a new customer, or 200 with created: false.
nullclears a field ("phone": null) or removes an attribute ("plan": null). Fields you leave out stay as they are.tagsadds and removes tags:{ "add": ["vip"], "remove": ["trial"] }. A customer has up to 20 tags.- A
phonethat a customer already wrote from on WhatsApp joins that conversation history to this customer. - If any attribute is invalid, nothing is written and the answer is
400with a message that names it, likeattributes.Plan: "Plan" is not a valid attribute key….
Update many at once
Send up to 100 customers in one call. Each one is applied on its own:
curl -X POST https://api.futurebase.io/v1/contacts/batch \
-H "Authorization: Bearer $FUTUREBASE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"contacts": [
{ "agentId": "YOUR_AGENT_ID", "externalId": "usr_8f2a", "attributes": { "plan": "pro" } },
{ "agentId": "YOUR_AGENT_ID", "email": "[email protected]", "name": "Marek Kowalski" }
]
}'The answer lists every item: { "results": [{ "index": 0, "status": 200, "contact": …, "created": false }, …] }. An item that failed has the status and error its own call would have answered with.
Look a customer up
curl "https://api.futurebase.io/v1/contacts/lookup?agentId=YOUR_AGENT_ID&externalId=usr_8f2a" \
-H "Authorization: Bearer $FUTUREBASE_API_TOKEN"Look up by externalId or email. To read a customer by FutureBase's own ID, call GET /v1/contacts/CONTACT_ID?agentId=YOUR_AGENT_ID. Both need contacts:read and answer { "contact": … } or 404.
A customer looks like this:
{
"id": "0193…",
"agentId": "YOUR_AGENT_ID",
"externalId": "usr_8f2a",
"email": "[email protected]",
"name": "Dana Ruiz",
"phone": null,
"company": "Northwind",
"avatarUrl": null,
"attributes": { "plan": "pro", "mrr": 49, "signed_up_at": "2026-03-02" },
"tags": ["vip"],
"verified": true,
"country": "ES",
"language": "es",
"lastChannel": "bubble",
"createdAt": "2026-03-02T10:00:00.000Z",
"firstSeenAt": "2026-03-02T10:00:00.000Z",
"lastSeenAt": "2026-11-03T08:12:00.000Z"
}Delete a customer
curl -X DELETE "https://api.futurebase.io/v1/contacts/CONTACT_ID?agentId=YOUR_AGENT_ID" \
-H "Authorization: Bearer $FUTUREBASE_API_TOKEN"This deletes the customer with their conversations and messages. Their feedback and tickets are kept without their details. It can't be undone.
Errors and limits
Errors are JSON: { "error": "A readable message", "code": "BAD_REQUEST" }.
| Status | When |
|---|---|
400 | The body or a value is invalid; the message says which |
401 | The token is missing, expired or revoked |
403 | The token lacks the scope, its owner is no longer an admin or owner, or the plan doesn't include the API |
404 | The agent or the customer wasn't found |
413 | The body is over 1 MB |
429 | Too many calls; wait for the number of seconds in Retry-After |
Each token can make 300 calls a minute, 30 batch calls a minute and 60 deletes a minute.
Who can change a customer
Anyone can type anything into a script tag, so FutureBase only trusts what it can verify:
- Your backend is trusted. The Customers API marks the customer as verified, and its values are never overwritten by the chat bubble.
- A signed chat bubble is trusted. With the identity check's
hash, the bubble's profile updates the verified customer, except for values that came from your backend or your team. - An unsigned chat bubble only fills in the blanks. Without a
hash, the profile updates a customer only while they aren't verified yet. Once they are verified, by the identity check, the API or a messaging app, unsigned profiles are ignored. - Your team has the last word. A value someone on your team sets on the customer's page is never overwritten by the chat bubble.
On the customer's page, hover a value to see where it came from: from your app, from the chat bubble or set by your team.
What your agent sees
Attributes are for your team first. Your agent can only use an attribute once you switch on Your agent can use it for it under Customers → Settings → Attributes, and only for signed-in customers. Every attribute starts switched off, so internal data like a risk score never reaches a customer by accident.
When a question depends on who the customer is ("what plan am I on?", "any news on my ticket?"), your agent looks up the customer it is talking to and answers in the same reply, without asking for their email first. It can only ever look up the person in the current conversation: the lookup takes no name, email or ID, so a visitor can't make it fetch someone else.
What it gets depends on how sure FutureBase is about who is chatting:
| Who is chatting | What your agent gets |
|---|---|
| A customer signed in through the identity check on this message, or anyone writing on Slack, WhatsApp, Telegram or Discord in a direct chat | Their name, email, company, when they became a customer, the attributes you switched on (under their labels, like "Plan"), their last 5 other conversations, up to 5 open tickets and up to 3 feedback items |
| A visitor who never signed in | Only the topics of earlier chats from the same browser |
| Anyone else, for example a visitor whose user ID isn't signed | Nothing. Your agent asks them to sign in on your website or offers a hand-off |
A few things never reach your agent, whoever is chatting:
- Tags and team notes
- Attributes that are switched off, and where an attribute's value came from
- Internal IDs, and anything about other customers
Your agent treats what it gets as facts, not instructions: an attribute that says "ignore your rules" is just text. It doesn't read the profile back to the customer or mention that it looked them up; it uses what it knows to skip questions and greets a signed-in customer by first name.
In Slack and Discord channels and Telegram groups, everyone in the chat reads your agent's replies, so it only looks customers up in direct messages.
Letting your agent look up customers and use attributes is on the Hobby plan and up.
Plans
| Free | Hobby | Standard and up | |
|---|---|---|---|
| Profile from the chat bubble and React | Ignored | Yes | Yes |
| Your agent can use attributes | No | Yes | Yes |
| Your agent looks up who it's helping | No | Yes | Yes |
| Saved views on Customers | No | 3 | Unlimited |
| Customers API | No | No | Yes |
Use the data
- Filter by attributes: on Customers, choose + Attribute to filter by any attribute: is, contains, greater or less than, before or after, or is set. Combine up to five.
- Save views: choose Save view to keep the filters as a tab, like "Pro trials" or "Churn risk". Everyone on your team sees it.
- Edit by hand: on a customer's page, edit, remove or add an attribute in the Attributes card.
See Managing conversations for more on the Customers list.