Client Engagement Chat

Provide a private, token-protected chat portal for individual clients with vector-retrieved context.

What you can do#

The client engagement chat provides a private, branded chat portal for individual clients. Each client gets a dedicated endpoint that draws on client-specific knowledge documents, with answers grounded in engagement materials relevant to that client.

Capability	Description	Status
Per-client portal	Unique URL per client slug	Shipped
Engagement-scoped grounding	Documents sourced from the engagement projection read-model	Shipped
Engagement token auth	Bearer-token validation via the engagement projection API	Shipped
Streaming chat	Real-time SSE streaming responses	Shipped
Conversation limits	Turn cap and message length validation	Shipped
Default-deny visibility	Visibility policy inherited from the engagement projection	Shipped

How it works#

Each client portal is accessed via a unique URL:

POST /api/clients/<client-slug>/chat
Authorization: Bearer <engagement-token>

When a user sends a message:

The engagement-scoped token is verified through the engagement projection API (resolveEngagementRequest) — the same auth path external integrations use.
The engagement is loaded with its enabled capabilities and audience scope.
Grounding documents are pulled from the engagement document read-model published by INIT-123, not the legacy filesystem RAG path.
The AI generates a streaming response grounded in the trusted engagement materials returned by the projection.

Knowledge sources#

Grounding documents come from the engagement projection's document read-model. Workspace integrators publish documents to the engagement index; the chat surface inherits the same default-deny visibility the static /clients/{slug} projection applies.

info The legacy filesystem RAG path (docs/clients/<slug>/) and the direct vector lookup against client_knowledge_documents are deprecated behind the engagement read model and only remain as source data for the document indexer.

Configuration#

Variable	Description
`SIDEKICK_PUBLIC_API_KEY`	API key for the AI model (required)
Engagement token	Issued per engagement via the projection API; presented as `Authorization: Bearer`

Limits#

Conversation turns -- maximum 10 turns per session
Message length -- 2,000 characters per message
Retrieval results -- bounded by the engagement document read model

Security#

Engagement-scoped auth -- every request requires a valid engagement token; workspace API keys and shared environment tokens are no longer accepted.
Client isolation -- each engagement slug resolves to its own projection scope; visibility policy is enforced by the loader.
Default-deny visibility -- the chat surface never sees content the static projection would have redacted.

warning Engagement tokens are per-engagement credentials. Treat them like API keys and rotate via the engagement token management surface if they may have been exposed.