Guides

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 user prop on ChatProvider
  • 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:

FieldWhat it is
nameTheir full name
phoneTheir phone number
companyTheir company's name
avatarUrlA picture of them, as an https URL
attributesAnything 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 keys name, email, phone, company and avatar are 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".
  • null removes 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.

  • null clears a field ("phone": null) or removes an attribute ("plan": null). Fields you leave out stay as they are.
  • tags adds and removes tags: { "add": ["vip"], "remove": ["trial"] }. A customer has up to 20 tags.
  • A phone that 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 400 with a message that names it, like attributes.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" }.

StatusWhen
400The body or a value is invalid; the message says which
401The token is missing, expired or revoked
403The token lacks the scope, its owner is no longer an admin or owner, or the plan doesn't include the API
404The agent or the customer wasn't found
413The body is over 1 MB
429Too 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 chattingWhat 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 chatTheir 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 inOnly the topics of earlier chats from the same browser
Anyone else, for example a visitor whose user ID isn't signedNothing. 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

FreeHobbyStandard and up
Profile from the chat bubble and ReactIgnoredYesYes
Your agent can use attributesNoYesYes
Your agent looks up who it's helpingNoYesYes
Saved views on CustomersNo3Unlimited
Customers APINoNoYes

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.

On this page