Webority.Chat.AspNetCore 0.145.2

webority-chat

Conversational component for assistant, support and sales chats: engine, React, Razor and React Native screens, server and admin.

Packages

Every package carries the one version in version.json.

Voice clips are players of stored clips only: the chat plays a clip that is already stored and does not record one.

A phone app that turns on Dictation or VoiceClips adds expo-audio's config plugin to its own app config, with the microphone permission text (Android RECORD_AUDIO), and ships a new store build.

Server wiring

services.AddWeborityChat<AppDbContext>()
    .AddLeadSink<WebsiteLeadSink>();
// OnModelCreating: modelBuilder.ApplyWeborityChatConfiguration();
app.MapWeborityChat("/api/chat", new ChatMapOptions { Surface = "website" });

Seeds are not registered in the web head. A product keeps each seed file in its database project, and a console calls ChatSeedSql.Write, which writes a run-once SQL script. The database project's build calls ChatSeedSql.Check, and the database gate applies each script once per deploy. Raising the seed's Revision re-applies it where the stored revision is lower. See docs/usage/server.md → Set up.

AddWeborityChat sends one-time codes by email, so every host registers Webority.Email, and adds the code template with AddWeborityChatOtpEmailTemplates() on its email builder. A host with lead capture also adds AddWeborityChatSalesEmailTemplates(), the template of the sales email sent to Chat:SalesNotificationEmail for each new lead.

Booking needs the host's IChatBookingSlots and IChatBookingSink, registered before or after AddWeborityChat. A chat whose profile turns booking on logs an error naming the missing seam when either is not registered, and the visitor sees the assistant-unavailable message.

AI replies: services.AddWeborityChatAi(surface, options) screens each message through an AI judge, so the host also registers one, for example AddWeborityAiJudgmentJev() with its key; startup fails without it. The four judgment uses (chat-injection, chat-topic, chat-sentiment, chat-repeat) default to the Jev provider (ChatAiUseDefaults); an Ai:Judgment:Uses entry overrides one.

Captcha: services.AddWeborityChatCaptcha() adds the gate over the host's ICaptchaVerifier (Webority.Security), and the browser receives that verifier's site key, so one stored profile works in every environment. A surface whose profile sets a captcha mode other than Off fails each turn with an error when the host never calls it.

The tables and their numbered migrations ship inside the Webority.Chat package under content/schema.

Admin pages: services.AddRazorPages().AddWeborityChatAdmin("ChatAdmin", leadUrlTemplate: "/Sales/Leads/{lead}", articleSuggestionUrlTemplate: "/Support/HelpCentre/New?question={question}&source={surface}"). The lead template holds {lead} once; the article template holds {question} once and {surface} at most once, and the Unanswered page shows "Suggest an article" only when it is set. Both are optional, and both start with https:// or a single /.

The transcript list is /Chat/Transcripts. Its scope query value, /Chat/Transcripts?scope=<scope key>, shows only the conversations stored under that scope key, matched exactly; the page shows the active scope with a Clear scope link.

Support wiring

Webority.Chat.Support adds handoff to a person, the agent console and away notices. Register it after AddWeborityChat and after the support builder's head call: AddCustomerService() on the customer head, AddAgentService() on the admin head, AddSystemService() on a background worker head.

// Customer head
var support = services.AddWeboritySupport<AppDbContext>().AddCustomerService().AddCustomerSuggestions();
services.AddWeborityAiActions<AppDbContext>(configuration);
support.AddChatTools();
services.AddWeborityChat<AppDbContext>();
services.AddWeborityChatSupport();
// OnModelCreating: modelBuilder.ApplyChatSupportConfiguration();
app.MapWeborityChat("/api/chat", new ChatMapOptions { Surface = "website" }).MapWeborityChatSupport(options);

// Admin head (also references Webority.Chat.Support.Admin)
var mvc = services.AddRazorPages();
services.AddWeboritySupport<AppDbContext>().AddAgentService();
mvc.AddWeborityChatSupportAdmin(agentPolicy);

Staff pages live only in Webority.Chat.Admin and Webority.Chat.Support.Admin. A customer or public head references neither.

Every head that calls AddWeborityChatSupport calls one of two methods on the AddWeborityOutbox builder: AddChatAwayOutbox() on the host that drains the chat-away queue (it sends the email and pushes), or AddChatAwayOutboxWriter() on a head that only queues away notices (no handler, so no push sender). It also sets Chat:Away:ConversationUrlTemplate to an absolute https URL containing {conversationId} when it sets the key. Startup fails otherwise.

• The host lists SupportTicketRaise in Ai:Actions:Kinds with Mode Confirm, and gives it a profile action cap (ChatActionCap: kind, max, window hours). The hand-off raises its ticket through that ledger entry.
• Chat:Support binds ChatSupportOptions (wait, idle, agent capacity, presence, typing and stream timings, with their ranges). Chat:Away binds the away notice options (docs/away-notices.md).
• A product timer calls ChatHandoffDeadlines.RunAsync once a minute. It ends a hand-off nobody took within MaxWaitMinutes.
• The ChatHandoff table and its numbered migration ship inside the Webority.Chat.Support package under content/schema, and run after the Webority.Chat baseline.
• Away notices need the host's IChatPushDevices when the recipient has devices, and a one-minute outbox processor for the chat-away queue. See docs/away-notices.md.
• The customer head calls AddWeborityChatOtpEmailTemplates() on its email builder for the visitor's one-time code (see Server wiring).

Visitors. A visitor's hand-off needs a confirmed email. When none exists, the hand-off asks for a name and an email, confirmed with a one-time code, and answers ChatHandoffStatus.ContactRequested until the contact is confirmed. The ticket is raised as a support contact (realm Contact), and staff see it only then. A host registers no IChatNotificationRecipients class unless it has devices. The customer head still registers ISupportCustomerContext for signed-in users, and it may throw for a public head with none.

Erasure and counts

ChatStore (registered by AddWeborityChat) deletes and counts a product's chat rows. Never query or delete the package's Chat* tables directly.

Each method returns the number of conversations. Messages and input requests go with their conversation. None needs an actor, so call them only from trusted server code.

public static async Task EraseChatAsync(ChatStore chat, string tenantScope, string surface, string linkPrefix, CancellationToken cancellationToken)
{
    var tenantFound = await chat.CountScopeAsync(tenantScope, cancellationToken);
    var tenantDeleted = await chat.DeleteScopeAsync(tenantScope, cancellationToken);
    var tenantLeft = await chat.CountScopeAsync(tenantScope, cancellationToken);
    if (tenantDeleted != tenantFound || tenantLeft != 0)
    {
        throw new InvalidOperationException("Chat rows remain after the tenant erasure.");
    }

    var familyFound = await chat.CountActorPrefixAsync(surface, linkPrefix, cancellationToken);
    var familyDeleted = await chat.DeleteActorPrefixAsync(surface, linkPrefix, cancellationToken);
    var familyLeft = await chat.CountActorPrefixAsync(surface, linkPrefix, cancellationToken);
    if (familyDeleted != familyFound || familyLeft != 0)
    {
        throw new InvalidOperationException("Chat rows remain after the shared link erasure.");
    }
}

Develop

corepack pnpm install --frozen-lockfile
corepack pnpm -r build
dotnet build Webority.Chat.slnx -v q --nologo -m:4
dotnet test --solution Webority.Chat.slnx --no-build

Two samples run the library locally:

• samples/FullStack.Host runs the whole chat on one machine: the real routes, a SQL Server database, the staff pages and a stand-in model with no network. Start with its README.md.
• samples/Razor.Sandbox is the database-free catalogue of the Razor chat, which the parity gate boots.

See CLAUDE.md for the repo rules.