Identity verification

When a customer is signed in to your store, you can tie their Bookbag conversations to a stable identity. That lets you group a person's chats, look up their history, and enrich the agent's context with what you already know about them.

Attach an end-user id

The simplest form of identity is the userId you pass on API v2 chat. It is your own stable identifier for the customer (for example your database user id). Bookbag stores it on the conversation so you can list everything that person has asked.

await fetch(`https://app.bookbag.ai/api/v2/agents/123/chat`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOOKBAG_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message: "Where is my last order?",
    userId: "user_8821",
    stream: false,
  }),
});

Enrich with contacts

To give the agent durable facts about a customer — plan, lifetime value, account status — sync them as a contact. Use the same stable id as the contact's external_id so the records line up:

curl https://app.bookbag.ai/api/v1/chatbots/123/contacts \
  -H "Authorization: Bearer $BOOKBAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "users": [ { "external_id": "user_8821", "email": "sam@acme.com", "custom_attributes": { "plan": "pro" } } ] }'

Define the custom attributes you want to store first, then attach values per contact. See the Contacts section for the full model.

A recommended flow

1. 1
   Authenticate on your side

   Identify the signed-in customer with your own session/auth — Bookbag does not authenticate end users for you.
2. 2
   Sync the contact

   Upsert the customer as a contact keyed by a stable external_id whenever their profile changes.
3. 3
   Proxy chat with the userId

   Send chat requests from your backend, passing the same id as userId, so conversations attach to the right person.
4. 4
   Read history when needed

   Use the per-user conversations endpoint to show a customer their past chats or to give agents context.