Web Widget Controller

While the Telephony Controller handles complex real-time audio streams, the Core API also powers the text-based conversational interfaces via the Web Widget Controller.

This controller acts as the backend for the rdv.ai-widget repository, which clients embed on their websites. The logic is primarily located in src/routes/widget.ts, src/routes/webagent.ts, and their respective src/controllers/ directories.

Architecture & Flow

Unlike telephony which relies on SIP webhooks, the Web Widget communicates with the Core API via standard REST endpoints (and Server-Sent Events / WebSockets for streaming responses).

1. Initialization & Configuration

When a website visitor opens the chat widget, the widget sends an initialization request to the Core API containing the client’s public identifier (e.g., a specific token or domain).

1. Fetching Config (src/controllers/webagent/config.ts): The API uses GenQL to query the Dashboard (Payload CMS) for this specific client’s configuration.
2. Branding & Prompts: It retrieves the custom greeting message, brand colors, and the hidden system prompt assigned to this web agent.
3. Session Creation: A unique conversation session is established to maintain message history.

2. Message Handling

When the user types a message and hits send:

1. State Management: The API appends the new message to the ongoing conversation history array.
2. Supervisor Check: Just like voice calls, the text input is run through the Supervisor model (src/services/llm/supervisor.ts) to determine if the user’s request requires calling an external tool (like searching a knowledge base or checking calendar availability).
3. LLM Routing: The complete context (System Prompt + History + New Message + Tool Results) is sent to the configured LLM (Google Gemini or OpenAI).
4. Streaming Response: To provide a snappy, ChatGPT-like experience, the API streams the LLM’s text response back to the widget chunk-by-chunk.

3. Database Logging

Text conversations are logged into the Dashboard just like phone calls, but they use a different collection (Chats or WebConversations).

After the interaction concludes (or periodically during the chat), the API uses the src/services/dashboard/webagent.ts service to mutate the database via GenQL. This ensures that the client can log into their dashboard and read the exact transcripts of what their website visitors are asking the AI.