sessions.create()

Open a session for the customer logged in to your product.

const { token, expiresAt } = await concatflow.sessions.create({
  assistantId: process.env.CONCATFLOW_ASSISTANT_ID!,
  partitions: { customer_id: req.user.customerId },
});

Call it from your server, for the customer your own session says is logged in. Hand token to the page. See Per-user door.

Parameters

assistantId · string · required

The assistant’s ID, a UUID. In its Integration tab.

partitions · Record<string, string | number> · required

Who the customer is, as your server knows it: { customer_id: "4712" }. The keys must be exactly the partition keys of the assistant’s signed isolation. Numbers are sent as strings.

Take the values from your session, never from the request.

Returns

token · string

An opaque token for init({ session }). It describes nothing and is only valid for this customer on this assistant.

expiresAt · string

ISO 8601 timestamp, 15 minutes after the call.

{ "token": "Qm8x…", "expiresAt": "2026-10-23T14:37:12.204000+00:00" }

Behaviour

• One conversation per customer. The first session for a partition creates the conversation. Later sessions, even concurrent ones, join it.
• Short tokens, long conversations. A token lasts 15 minutes. The conversation stays until you erase it.
• No customer data in the browser. The partition stays on Concatflow’s side. Only its hash is used to find the conversation.

Validation

These throw a TypeError before any request:

• assistantId is empty or not a string;
• partitions is not an object, or has no key;
• a key or value is empty, or a number is not finite.

The API also refuses values over 200 characters and keys over 63.

Errors

Status	Code	Meaning
400	invalid_body	assistantId is not a UUID, or the body is malformed.
401	invalid_api_key	The key is wrong or revoked.
403	partition_keys_mismatch	The keys differ from the isolation’s. err.body.detail.expected lists the right ones.
404		Unknown assistant, or one from another workspace.
409	not_published	The assistant is not published.
409	door_closed	The per-user door is off.
409	isolation_unsigned	The isolation is not signed.

All errors are in Errors.