Anonymous Chat

Once a build is ready, visitors chat with the agent using its public slug. This is the existing anonymous public surface — no API key, slug-based, with anonymousId sessions and optional SSE streaming. Because no secret is involved, the browser calls these endpoints directly (no backend proxy needed for chat).

anonymousId MUST be a UUID (e.g. crypto.randomUUID()). Generate one per visitor, persist it (e.g. localStorage), and reuse it across the conversation.

Create Conversation

Start a conversation and (if configured) receive a welcome message.

Path Parameters

string

required

The agent’s public slug — the agentSlug from the ready event.

Request Body

string

required

A UUID identifying the anonymous visitor session.

Response (200)

boolean

Request status.

object

Show data object

string

New conversation UUID.

string

Welcome message content, if the agent has one configured.

curl -X POST https://app.brainstormer.io/api/public/agents/the-channel-agent/conversations \
  -H "Content-Type: application/json" \
  -d '{ "anonymousId": "550e8400-e29b-41d4-a716-446655440000" }'

const anonymousId =
  localStorage.getItem("bsio_anon") ??
  (() => {
    const id = crypto.randomUUID();
    localStorage.setItem("bsio_anon", id);
    return id;
  })();

const res = await fetch(
  `https://app.brainstormer.io/api/public/agents/${slug}/conversations`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ anonymousId }),
  },
);
const { data } = await res.json();
const { conversationId, welcomeMessage } = data;

Response (200):

{
  "success": true,
  "data": {
    "conversationId": "c1a2b3c4-d5e6-7f80-9a1b-2c3d4e5f6071",
    "welcomeMessage": "Hey! Ask me anything about my videos."
  }
}

Send Message

Send a message in a conversation. Returns a full response, or an SSE token stream when stream: true.

Path Parameters

string

required

The agent’s public slug.

Request Body

string

required

The visitor’s message.

string

required

The UUID returned by create-conversation.

string

required

The same UUID used to create the conversation.

boolean

default:"false"

Set true to receive an SSE token stream instead of a single JSON response.

array

Up to 5 files to attach to this message. Each item is { id, accessToken } returned by Upload Attachment. Only available when the agent has file uploads enabled.

Response (200) — non-streaming

string

The agent’s reply.

string

The conversation UUID.

object

Token usage and cost info.

curl -X POST https://app.brainstormer.io/api/public/agents/the-channel-agent/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What gear do you recommend?",
    "conversationId": "c1a2b3c4-d5e6-7f80-9a1b-2c3d4e5f6071",
    "anonymousId": "550e8400-e29b-41d4-a716-446655440000"
  }'

const res = await fetch(
  `https://app.brainstormer.io/api/public/agents/${slug}/chat`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      message: "What gear do you recommend?",
      conversationId,
      anonymousId,
    }),
  },
);
const data = await res.json();
console.log(data.response);

Streaming (SSE)

Add "stream": true to receive a token stream. The browser can read it directly with a fetch body reader:

Browser — streaming

const res = await fetch(
  `https://app.brainstormer.io/api/public/agents/${slug}/chat`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ message, conversationId, anonymousId, stream: true }),
  },
);

const reader = res.body!.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  for (const line of decoder.decode(value).split("\n")) {
    if (!line.startsWith("data: ")) continue;
    const evt = JSON.parse(line.slice(6));
    if (evt.token) process.stdout.write(evt.token); // append to the UI
    if (evt.done) console.log("\n", evt.usage);
  }
}

Upload Attachment

Upload a file from the browser to attach to a chat message. Anonymous and slug-scoped — no API key. Only works when the agent has file uploads enabled; otherwise returns 403. Send the file as multipart/form-data under the field name file, with the visitor’s anonymousId in the query string.

Path Parameters

string

required

The agent’s public slug.

Query Parameters

string

required

The visitor’s UUID (the same one used for conversations).

Request

multipart/form-data with a single file part. Limits: max 5 files per message, size + type enforced server-side (images, PDF, text, audio, video). Content is magic-byte sniffed, so a file whose bytes don’t match its declared type is rejected (415).

Response (200)

object

{ id, accessToken, fileType, originalFilename, fileSizeBytes, contentType, processingStatus, createdAt }. Pass { id, accessToken } in the chat message’s attachments array.

curl -X POST "https://app.brainstormer.io/api/public/agents/the-channel-agent/attachments?anonymousId=550e8400-e29b-41d4-a716-446655440000" \
  -F "file=@./photo.png"

// 1. Upload, then 2. send the returned ref with the next message.
async function uploadAndSend(slug, anonymousId, conversationId, file, message) {
  const form = new FormData();
  form.append("file", file);
  const up = await fetch(
    `https://app.brainstormer.io/api/public/agents/${slug}/attachments?anonymousId=${anonymousId}`,
    { method: "POST", body: form }, // do NOT set Content-Type — the browser adds the boundary
  );
  if (!up.ok) throw new Error(`Upload failed (${up.status})`);
  const { attachment } = await up.json();

  return fetch(`https://app.brainstormer.io/api/public/agents/${slug}/chat`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      message,
      conversationId,
      anonymousId,
      attachments: [{ id: attachment.id, accessToken: attachment.accessToken }],
    }),
  });
}

Uploads are rate-limited per IP and per anonymousId. The accessToken is a per-upload secret returned only to the uploader — it’s the ownership proof when you reference the attachment in a message, so don’t expose it elsewhere.

List Conversations

List the conversations belonging to an anonymous visitor for this agent.

Path Parameters

string

required

The agent’s public slug.

Query Parameters

string

required

The visitor’s UUID (the same one used to create the conversations).

number

default:"20"

Maximum results.

number

default:"0"

Pagination offset.

Response (200)

object[]

Array of the visitor’s conversations.

object

Show pagination object

number

boolean

curl "https://app.brainstormer.io/api/public/agents/the-channel-agent/conversations?anonymousId=550e8400-e29b-41d4-a716-446655440000&limit=20&offset=0"

const res = await fetch(
  `https://app.brainstormer.io/api/public/agents/${slug}/conversations?anonymousId=${anonymousId}&limit=20&offset=0`,
);
const { conversations, pagination } = await res.json();

Get Messages

Retrieve the messages in one of the visitor’s conversations.

Path Parameters

string

required

The agent’s public slug.

string

required

The conversation UUID.

Query Parameters

string

required

The visitor’s UUID (the same one used to create the conversation).

number

default:"50"

Maximum results.

number

default:"0"

Pagination offset.

Response (200)

object[]

Array of message objects in the conversation.

curl "https://app.brainstormer.io/api/public/agents/the-channel-agent/conversations/c1a2b3c4-d5e6-7f80-9a1b-2c3d4e5f6071/messages?anonymousId=550e8400-e29b-41d4-a716-446655440000"

const res = await fetch(
  `https://app.brainstormer.io/api/public/agents/${slug}/conversations/${conversationId}/messages?anonymousId=${anonymousId}`,
);
const { messages } = await res.json();

Rename Conversation

Rename one of the visitor’s conversations.

Path Parameters

string

required

The agent’s public slug.

string

required

The conversation UUID.

Request Body

string

required

The visitor’s UUID (the same one used to create the conversation).

string

required

The new conversation title. 1–80 characters.

Response (200)

object

The updated conversation object.

curl -X PATCH https://app.brainstormer.io/api/public/agents/the-channel-agent/conversations/c1a2b3c4-d5e6-7f80-9a1b-2c3d4e5f6071 \
  -H "Content-Type: application/json" \
  -d '{
    "anonymousId": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Camera gear questions"
  }'

const res = await fetch(
  `https://app.brainstormer.io/api/public/agents/${slug}/conversations/${conversationId}`,
  {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ anonymousId, title: "Camera gear questions" }),
  },
);
const { conversation } = await res.json();

Delete Conversation

Delete one of the visitor’s conversations. This is how a visitor clears one conversation from their history.

Path Parameters

string

required

The agent’s public slug.

string

required

The conversation UUID.

Query Parameters

string

required

The visitor’s UUID (the same one used to create the conversation).

Response (200)

boolean

true on success.

curl -X DELETE "https://app.brainstormer.io/api/public/agents/the-channel-agent/conversations/c1a2b3c4-d5e6-7f80-9a1b-2c3d4e5f6071?anonymousId=550e8400-e29b-41d4-a716-446655440000"

const res = await fetch(
  `https://app.brainstormer.io/api/public/agents/${slug}/conversations/${conversationId}?anonymousId=${anonymousId}`,
  { method: "DELETE" },
);
const { success } = await res.json();

Operator Presence (SSE)

Subscribe to real-time operator-presence / human-in-the-loop events for a conversation — operator messages, takeover/join, and resolution. Use EventSource (the anonymousId rides in the query string since EventSource can’t set headers); the server validates that the visitor owns the conversation.

Query Parameters

string

required

The visitor’s UUID (must own the conversation).

Stream

text/event-stream. The first event is {"type":"connected"}; subsequent data: events carry operator/HITL payloads (e.g. {"type":"operator_message", ...}, {"type":"operator_joined", ...}, {"type":"hitl_resolved", ...}).

Browser / TypeScript

const es = new EventSource(
  `https://app.brainstormer.io/api/public/agents/${slug}/conversations/${conversationId}/events?anonymousId=${anonymousId}`,
);
es.addEventListener("message", (e) => {
  const evt = JSON.parse(e.data);
  if (evt.type === "operator_message") appendOperatorMessage(evt);
});
// es.close() when the conversation view unmounts.

This is the visitor side. The chat-core PublicTransport.subscribeEvents wires it automatically. The operator side (sending messages, taking over) runs through the authenticated HITL operator dashboard.

Notes

The browser calls these endpoints directly — no brs_live_ key, no backend proxy. Only provisioning is gated.
Any per-visitor message cap (e.g. an email gate after N messages) is a client UX concern, not an API limit.
Seed the chat UI with the starterQuestions from the ready ProvisioningEvent.

​Anonymous Chat

​Create Conversation

​Path Parameters

​Request Body

​Response (200)

​Send Message

​Path Parameters

​Request Body

​Response (200) — non-streaming

​Streaming (SSE)

​Upload Attachment

​Path Parameters

​Query Parameters

​Request

​Response (200)

​List Conversations

​Path Parameters

​Query Parameters

​Response (200)

​Get Messages

​Path Parameters

​Query Parameters

​Response (200)

​Rename Conversation

​Path Parameters

​Request Body

​Response (200)

​Delete Conversation

​Path Parameters

​Query Parameters

​Response (200)

​Operator Presence (SSE)

​Query Parameters

​Stream

​Notes

Anonymous Chat

Create Conversation

Path Parameters

Request Body

Response (200)

Send Message

Path Parameters

Request Body

Response (200) — non-streaming

Streaming (SSE)

Upload Attachment

Path Parameters

Query Parameters

Request

Response (200)

List Conversations

Path Parameters

Query Parameters

Response (200)

Get Messages

Path Parameters

Query Parameters

Response (200)

Rename Conversation

Path Parameters

Request Body

Response (200)

Delete Conversation

Path Parameters

Query Parameters

Response (200)

Operator Presence (SSE)

Query Parameters

Stream

Notes