Application Architectures: How Your Users Map onto the Platform

Overview

There are many shapes of application you can build on top of ChatBotKit, from a one-file command-line tool to a fully branded multi-tenant platform you resell. They look very different on the surface, but they are distinguished by a single underlying decision: what is an end user, in platform terms?

The platform gives you a small set of identity primitives - a token holder, a contact, a sub-account, a portal user, a bot session. Every application architecture is, at heart, a choice about which of those an end user becomes. That one choice cascades into everything else: how the user authenticates, what isolation they get, where their conversations and memory live, how usage is billed, and how much of a UI you have to build yourself.

This guide enumerates the common architectures and ties each one back to that decision, so the shape you pick is deliberate rather than the accident of how you happened to start.

This is a different cut than the agent deployment guide. That guide is about the operator axis - environments, account topology, and reproducible infrastructure-as-code pipelines. This one is about the product axis - how the people who use your product map onto the platform. The two are orthogonal: any architecture here is deployed through some topology there.

The Organizing Question

Hold one question in mind throughout: when a person uses what I am building, what do they become on the platform?

The answers form a spectrum, ordered roughly by how heavyweight the per-user identity is:

The rest of the guide takes each in turn. They are not exclusive - most real products combine two or three - but it is cleaner to understand them one at a time and then compose.

CLI Agents

What it is. A command-line program - or any thin, single-operator client - that drives an agent directly. There is no multi-user surface and no durable per-end-user record; the operator running the tool is the user. This is the same core/runtime split described in the centralized agent runtime guide, reduced to a single local shell.

An end user is the token holder. There is no contact and no account mapping for "users," because there is only one: whoever holds the credential.

Auth model. Two shapes, and you mentioned both:

• Scoped session token, used directly. The CLI carries a short-lived bot session token (or a narrowly-scoped mint token that can do nothing but open sessions for one bot) and drives a conversation against it. The agent's backstory, model, knowledge, and policy all live on the platform; the CLI specifies none of them. This keeps the embedded credential weak - even if it leaks, it can only run the one agent it was already running. See the security reasoning in the AI agent security guide.
• Through a proxy. The CLI talks to your own server, which holds the account secret and brokers each call. The secret never reaches the client machine; the client gets only what the proxy chooses to expose. This is the right shape when the CLI is distributed to people you do not fully trust with a token.

When to use. Internal operator tooling, developer agents, batch/automation jobs, edge runtimes, anything where there is a single principal per process and no end-user population to model.

Embedded / Widget Agents

What it is. A production-grade agent dropped into a website or mobile app through the widget and its SDK. Integration is minutes of work - you do not build the chat UI, you embed it. See the embedded solution.

An end user is a session, optionally promoted to a contact. A first-time anonymous visitor is just a conversation; once you attach a stable fingerprint (or a known email/identifier), that session becomes a durable contact that accumulates history, memory, and personalization across visits.

Auth model. Your backend mints a bot session token - POST /api/v1/bot/{botId}/session/create, optionally carrying a contact block - and hands it to the widget. The token is time-limited (30 minutes to 24 hours) and scoped to the one bot, so your account secret stays server-side. Verified contacts use a trusted fingerprint; unverified ones are created automatically from interaction.

When to use. Customer-facing support, sales, and assistant experiences on web and mobile where you want a polished chat surface without building one, and where users range from anonymous visitors to logged-in customers.

Messaging Agents

What it is. An agent that lives entirely inside the messaging platforms people already use - Slack, Discord, WhatsApp, Telegram, Messenger, email. There is no other UI; the messaging app is the interface. See the messaging solution.

An end user is a contact, keyed by the channel handle. A Slack user, a WhatsApp number, or a Discord tag maps to a contact (the nick field typically carries the handle), created automatically as people interact. All of those contacts live inside a single account alongside the bot and the channel integrations.

Auth model. No per-user token at all. You configure the channel integration once in the account; the platform handles inbound and outbound delivery. The identity work is the platform's - it resolves each inbound message to the right contact and conversation.

When to use. Internal team assistants, community bots, and customer support that should meet users where they are. This is the lowest-effort architecture to stand up when you already have a messaging surface and do not want to build or host any app of your own.

Single-Account Apps

What it is. Your own application - your UI, your auth, your product - backed by one ChatBotKit account. Inside that account you may have one agent or many, and your users can reach any of them through your interface.

An end user is a contact in that single shared account. Your account holds the resources; each of your users is represented as a contact, and their conversations, memories, and tasks hang off that contact record. This is the shape you described: the user has access to one or many agents, but on the platform their identity is a contact.

Auth model. The proxy pattern. Your backend holds one account secret and never exposes it. For each signed-in user it calls contact/ensure with a stable fingerprint to resolve the contact, then mints a per-user bot session token for the browser. Every user shares one resource set, one conversation store, one usage pool, and one bill.

When to use. The default for most SaaS products with an AI feature. Users do not need isolated infrastructure from each other - they need isolated data (their own conversations and memory), which contacts give you, while you keep one simple account to operate. Cap exposure with the proxy and per-bot session scoping.

Trade-off. All users share one account boundary. If a user must have their own resources, their own secrets, their own configurable agents, or a guaranteed slice of capacity, a contact is too thin a wall - and you want the next architecture.

Multi-Account Apps

What it is. Your application, where each user gets their own bespoke environment - a sub-account of their own, with isolated resources, conversations, secrets, and limits. This is the product-side view of Pattern B / hybrid in the deployment guide, and it leans on the Partner API.

An end user is a sub-account. The full account boundary sits between one user and the next: their bots, datasets, integrations, and conversation history are invisible to every other user by default.

Auth model. Your backend holds the master secret and uses the partner clients to create a sub-account when a user signs up, then operates each one either through a per-sub-account token or through the run-as mechanism (CHATBOTKIT_API_RUNAS_USERID / runAsUserId). A single piece of backend code can serve every tenant by switching the run-as target.

When to use. When users build and configure their own agents, bring their own integrations and credentials, need hard isolation from one another, or require a dedicated capacity ceiling (set per-sub-account token limits). Anything that feels like "each customer gets their own workspace" lands here.

Trade-off. More moving parts: you provision and tear down accounts, and you manage a high-privilege master credential carefully (treat it like an AWS root key). Billing still rolls up to the master unless you split customers across master accounts - see the cost-allocation discussion in the deployment guide.

Portal Apps

What it is. Access to ChatBotKit's own first-party applications - Chat, Inbox, Studio, and others - exposed to a defined set of users through a branded portal, on its own domain. You do not build the UI; the platform's apps are the UI, wrapped and scoped by the portal.

An end user is a portal user. Portal users authenticate to the portal (which has its own auth, authorization, and groups), receive no API token, and see only the apps the portal exposes - nothing of the wider account.

Auth model. The portal owns authentication and access control. This inverts the usual question: a team grants access to an account; a portal grants access to an application. It is the right tool for the wider organization - QA reviewers, content authors, customer-success staff, external partners - who need a specific app surface and should never hold a credential or see the account behind it.

When to use. When the people you are granting access to are non-operators who need a focused app (review conversations, author knowledge, run a chat surface) rather than the ability to build agents. Covered in depth under Teams and Access Control in the deployment guide.

White-Label Platforms

What it is. Your own branded AI-agent platform, sold to your customers, running on ChatBotKit infrastructure. Each customer operates their own environment under your brand, on your domain, without ever seeing ChatBotKit. See the white-label solution and the marketplace and white-label patterns in the resource sharing guide.

An end user is a customer who runs their own sub-account. White-label is the multi-account architecture plus branding and resale: each customer gets a fully isolated sub-account under your master account, presented through branded portals (custom domain, logo, theme) so the experience feels native to your product. Inside their sub-account, a customer can themselves run any of the earlier architectures - embed a widget, wire up messaging, build their own agents.

Auth model. You hold the master credential and own the relationship. Customers authenticate into your branded surface (portals, or your own app over the partner API); shared building blocks can be published once and reused across customer sub-accounts through the protected-visibility model described in the resource sharing guide.

When to use. When you are reselling AI agents under your own brand and your customers need isolated, self-contained environments - an agency, a vertical SaaS embedding agents for each client, or a platform business built on top of ChatBotKit.

Architectures Compose

These are building blocks, not mutually exclusive boxes. Real products usually combine several:

• A single-account app that also exposes a widget for anonymous visitors and an Inbox portal for the support team to triage them.
• A multi-account app where each customer's sub-account runs a messaging integration into their own Slack, while you operate the fleet from one runtime.
• A white-label platform whose customers each get a sub-account, inside which they embed widgets and connect messaging channels to agents they build themselves.

The composition is clean because the primitives nest predictably: contacts live inside an account; sub-accounts live inside a master account; portals and widgets are surfaces onto whichever account they point at.

Choosing an Architecture

Walk the same question down a short ladder:

1. Is there a population of end users to model at all? If no - single operator, automation, batch - you want CLI agents. Stop here.
2. Do users need isolation from one another?
   • No, they only need their own conversation history and personalization → they are contacts. Use a single-account app, or messaging if a chat channel is the whole UI, or a widget if you are embedding into an existing site.
   • Yes, they need their own resources, secrets, agents, or capacity → they are sub-accounts. Use a multi-account app.
3. Are the users non-operators who need a focused app surface, not a build environment? → Portal apps.
4. Are you reselling the whole thing under your own brand? → White-label platform (multi-account + portals + branding).

And the inverse, as a sanity check: pick the lightest identity primitive that still gives each user the isolation they genuinely need. Reaching for sub-accounts when contacts would do adds provisioning and credential-management cost for no benefit; reaching for contacts when you needed sub-accounts means discovering halfway in that one user can see another's resources.

Relationship to Deployment

Architecture (this guide) and deployment topology (the deployment guide) are independent choices that meet at one point: the multi-account app and white-label architectures are built from the very same sub-account mechanism that the deployment guide uses for per-tenant isolation in Pattern B and the hybrid pattern. The difference is framing - here a sub-account is an end user's environment; there it is a unit of deployment isolation. They are the same primitive seen from two sides, so the Partner API, run-as, and per-sub-account limits carry over directly.

Everything else composes orthogonally: a single-account app, a widget, or a messaging agent is still deployed across dev/staging/production accounts using whichever topology and pipeline the deployment guide recommends.

Summary

Every application you build on ChatBotKit answers one question first - what is an end user, in platform terms? - and that answer is what distinguishes the architectures:

• CLI agents - the user is the token holder; no population to model. Direct scoped session token, or a proxy.
• Embedded / widget agents - the user is a session, optionally a contact; you embed rather than build the UI.
• Messaging agents - the user is a contact keyed by channel handle; the messaging app is the entire interface.
• Single-account apps - the user is a contact in one shared account; your backend proxies a single secret and mints per-user sessions.
• Multi-account apps - the user is a sub-account with a fully isolated environment; your backend provisions and drives them via the Partner API.
• Portal apps - the user is a portal user with no API token, scoped to first-party apps.
• White-label platforms - the user is a customer running their own branded sub-account; multi-account plus branding and resale.

Pick the lightest primitive that gives each user the isolation they actually need, compose architectures freely, and remember that the heavier two (multi-account and white-label) are the product-side face of the sub-account topology in the deployment guide.