---
title: "Web Chatbots Module Documentation"
description: "Documentation for Web Chatbots"
---

## Table of Contents
1. [Navigation & Access](#navigation--access)
2. [Screenshots & Visual Interface](#screenshots--visual-interface)
3. [🎯 User Roles & Key Capabilities](#-user-roles--key-capabilities)
4. [Module Overview (Technical)](#1-module-overview-technical)
5. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
6. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
7. [Chatbot Persona & Behavioral Configuration](#4-chatbot-persona--behavioral-configuration)
8. [Knowledge Base & Retrieval-Augmented Generation (RAG)](#5-knowledge-base--retrieval-augmented-generation-rag)
9. [Tool Profiles & Action Execution](#6-tool-profiles--action-execution)
10. [Human Agent Handoff & Escalation](#7-human-agent-handoff--escalation)
11. [Settings Reference](#8-settings-reference)
12. [Common Scenarios & Best Practices](#9-common-scenarios--best-practices)
13. [Model Context Protocol (MCP) AI Integration](#model-context-protocol-mcp-ai-integration)
14. [Troubleshooting & Diagnostics](#10-troubleshooting--diagnostics)
15. [Glossary](#11-glossary)
---

## Navigation & Access

To access the Web Chatbots module:
1. Log in to the Ring2All Web Portal (`https://<domain-or-ip>/login`).
2. In the left navigation sidebar, expand **Administration**.
3. Under **AI Integration**, click **Web Chatbots** (`/admin/ai-integration/chatbots`).
4. Review registered interactive web chatbots, default status badges, assigned LLM profiles, and activity telemetry.
5. Click **+ Add** to create a new conversational web chatbot (`/admin/ai-integration/chatbots/new`), or edit existing assistant personas and knowledge bases.

---

## Screenshots & Visual Interface

### Web Chatbots Directory
Central repository displaying active web chat assistants, linked AI profiles, default corporate bot badges, and quick actions for testing, prompt tuning, or session review.
![Web Chatbots Directory](/screenshots/admin/ai/ai-chatbots-list.png)

### Web Chatbot Persona & Knowledge Configuration Form
Multi-section configuration editor for naming the assistant, selecting foundation models, crafting system prompts, setting response styles, binding RAG knowledge bases, and attaching operational tool profiles.
![Web Chatbot Configuration Form](/screenshots/admin/ai/ai-chatbots-form.png)

---

## 🎯 User Roles & Key Capabilities

| Role | Access Level | Responsibilities & Capabilities |
| :--- | :--- | :--- |
| **PBX Super Administrator** | Full Access (`RW`) | Provision and configure interactive web chatbots, assign foundation AI profiles and RAG vector indexes, and designate the default corporate copilot. |
| **Customer Experience Manager** | Persona & Prompt Design (`RW`) | Author system prompts, calibrate conversational personas and tones, review chat session satisfaction ratings, and attach operational tool profiles. |
| **Knowledge Base Specialist** | RAG Management (`RW`) | Ingest technical manuals, policy PDFs, and FAQs into vector storage (`pgvector`), optimizing chunk sizes and similarity thresholds. |
| **AI Platform Copilot / MCP Agent** | Diagnostic Inspection (`RO`) | Execute `get_ai_chatbot_status` to evaluate active chatbot personas, system instructions, and user or extension copilot bindings. |

---

## 1. Module Overview (Technical)

### What Are Web Chatbots?

**Web Chatbots** are intelligent text-based conversational agents embedded directly within the Ring2All Web Portal, User Portal, and external website widgets. Powered by state-of-the-art LLMs (OpenAI GPT-4o, Anthropic Claude, or local Ollama/LM Studio models), chatbots deliver 24/7 automated tier-1 customer support, internal company knowledge retrieval, and automated workflow triggers.

### Architecture

```
┌────────────────────────────────────────────────────────────────────────────────────────┐
│                          Web Chatbot Architecture & Workflow                           │
├────────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                        │
│  User Chat Session (Web Portal / External Widget)                                      │
│       │                                                                                │
│       ▼ WebSocket / REST API                                                           │
│  ┌──────────────────────────────────────────────────────────────────────────────────┐  │
│  │ Fastify Web Chat Engine (ring2all/api)                                           │  │
│  │ ├─ Session Context Manager (Redis / PostgreSQL)                                 │  │
│  │ ├─ System Persona & Boundary Injection                                           │  │
│  │ └─ Prompt Assembly Pipeline                                                      │  │
│  └──────────────────────────────────────┬───────────────────────────────────────────┘  │
│                                         │                                              │
│       ┌─────────────────────────────────┼──────────────────────────────────┐           │
│       ▼                                 ▼                                  ▼           │
│  ┌─────────────────────────┐   ┌─────────────────────────┐   ┌───────────────────────┐ │
│  │ Knowledge Base (RAG)    │   │ Tool Profile Execution  │   │ AI Provider & Profile │ │
│  │ pgvector cosine match   │   │ MCP Tool Dispatcher     │   │ GPT-4o / Claude 3.5   │ │
│  │ Internal manuals & PDFs │   │ CRM, Ticketing, Billing │   │ Streaming Token Feed  │ │
│  └─────────────────────────┘   └─────────────────────────┘   └───────────────────────┘ │
│       │                                 │                                  │           │
│       └─────────────────────────────────┼──────────────────────────────────┘           │
│                                         ▼                                              │
│  Interactive Response Delivered to Caller / Customer                                  │
│                                                                                        │
└────────────────────────────────────────────────────────────────────────────────────────┘
```

---

## 2. Module Overview (Commercial/Business)

### Business Value

* **24/7 Omnichannel First Response**: Resolves up to 70% of routine inquiries without human intervention.
* **Seamless Escalation to PBX**: Enables callers to escalate from web chat directly into a SIP ring group or queue.
* **White-Label Corporate Assistants**: Customize tone, brand guidelines, and knowledge scope for each enterprise tenant.

---

## 3. Module Overview (End User/Administrator)

Administrators can:
1. Create and manage multiple specialized chatbots (e.g. Sales Concierge, IT Helpdesk, Billing Inquiries).
2. Designate one chatbot as the **Default Corporate Assistant** for user portals.
3. Upload PDF documents, company handbooks, and FAQs to ground responses in verified facts.
4. Review chat history to audit agent answers and identify knowledge gaps.

---

## 4. Chatbot Persona & Behavioral Configuration

* **Agent Name & Display**: Public-facing name and title shown in the chat window.
* **Tone & Persona**: Selection of communication styles (`professional`, `friendly`, `calm`, `enthusiastic`).
* **System Prompt (Instruction Matrix)**: Guardrails defining what the bot can and cannot discuss.
* **Response Length**: Choose between `brief` (quick answers) and `detailed` (in-depth explanations).

---

## 5. Knowledge Base & Retrieval-Augmented Generation (RAG)

1. **Document Upload**: Ingest company documentation in `.pdf`, `.docx`, `.md`, or `.txt` formats.
2. **Chunking & Vectorization**: Automated document splitting and vector generation via the configured embedding profile.
3. **Semantic Retrieval**: Queries retrieve top matching context chunks using cosine distance (`<=>`) before generating responses, preventing hallucinations.

---

## 6. Tool Profiles & Action Execution

Attach an **AI Tool Profile** to empower chatbots with functional execution:
* Look up customer records in CRM by email or phone.
* Create escalation tickets in Jira Service Management or Zendesk.
* Check shipping and order delivery statuses.

---

## 7. Human Agent Handoff & Escalation

When a customer's query exceeds automated capabilities or sentiment detection indicates frustration:
* The chatbot can trigger an automated handoff event.
* A SIP call is initiated to a designated queue, or the session is routed to a human operator in the Switchboard interface.

---

## 8. Settings Reference

| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `agent_name` | String(100) | Required | Friendly name of the chatbot assistant. |
| `agent_type` | String | `'chat'` | Differentiates web chatbots from voice agents. |
| `ai_profile_id` | Integer | Required | Foundation LLM model used for chat generation. |
| `is_default_chatbot`| Boolean | `false` | Marks assistant as default for the domain's user portal. |
| `personality` | Enum | `'professional'` | Tone: `professional`, `friendly`, `calm`, `enthusiastic`. |
| `tool_profile_id` | Integer | Nullable | References `public.ai_tool_profiles(id)`. |

---

## 9. Common Scenarios & Best Practices

1. **Public Website Lead Qualifier**: Collects visitor contact information, verifies budget and timeline, and notifies sales reps via email/SMS.
2. **Internal Telecom Wiki Bot**: Answers technician queries regarding PBX codes, dialplan routes, and SIP configurations.

---

## Model Context Protocol (MCP) AI Integration

The **Web Chatbots** module integrates with the SoftSwitch Model Context Protocol (MCP) server, enabling platform assistants, supervisory copilots, and administrative diagnostics to inspect active conversational agent personas, system prompt instructions, and user bindings.

### MCP Tools Catalog

| Tool Name | Type | Access | Description |
| :--- | :--- | :--- | :--- |
| `get_ai_chatbot_status` | Query | `ai_system_admin` / Read | Queries active AI Chatbot configuration, assistant persona name, system prompts, greeting message, and model assignments. |

### Tool Schemas & Execution Responses

#### `get_ai_chatbot_status`
```json
{
  "name": "get_ai_chatbot_status",
  "description": "Queries active AI Chatbot configuration, assistant persona name, system prompts, greeting message, and model assignments.",
  "parameters": {
    "type": "object",
    "properties": {
      "user_id": {
        "type": "number",
        "description": "Optional admin user ID to inspect user-specific copilot profile."
      },
      "extension_id": {
        "type": "number",
        "description": "Optional extension ID to inspect extension-specific assistant."
      }
    }
  }
}
```

**Realistic Execution Response:**
```json
{
  "success": true,
  "data": {
    "chatbot": {
      "hasChatbot": true,
      "agentName": "Corporate Support Concierge",
      "personaName": "Sofía AI Assistant",
      "greetingMessage": "Hello! Welcome to Ring2All Platform support. How may I assist you with your telephony or billing questions today?",
      "closingMessage": "Thank you for contacting us! If you need further assistance, our engineers are always available.",
      "userId": 1,
      "extensionId": 1001
    }
  }
}
```

### Bilingual Natural Language Prompt Examples

#### English Prompts
- *"Copilot, check the active AI chatbot configuration for user ID 1."*
- *"What is the opening greeting message configured for the default web assistant?"*
- *"Verify if an assistant persona is attached to extension 1001."*

#### Spanish Prompts
- *"Copilot, consulta el estado de configuración del chatbot de IA para el usuario 1."*
- *"¿Cuál es el mensaje de saludo inicial configurado para el asistente web por defecto?"*
- *"Verifica si la extensión 1001 tiene un chatbot o persona de asistente asignada."*

### Enterprise Safeguards & Execution Boundaries
1. **Multi-Tenant Domain Scoping:** Chatbot lookup strictly enforces numeric `domain_id` and `tenant_id` boundaries, preventing cross-tenant assistant exposure.
2. **Context Window Protection:** System prompts and RAG contexts are validated against model context limits to prevent unexpected token truncation during runtime conversation.
3. **No Unauthenticated Execution:** Web chatbot endpoints require authenticated sessions or verified tenant tokens for external embedded widgets.

---

## 10. Troubleshooting & Diagnostics

* **Chatbot Not Responding**: Check that the linked AI Profile in **AI Profiles** has an active provider with valid API keys.
* **Hallucinations**: Ensure RAG context documents are uploaded and verify that system prompt instructions include explicit boundary rules (e.g., "Only answer based on provided context").

---

## 11. Glossary

* **Web Chatbot**: Text-based conversational AI agent hosted in web portals or external embeds.
* **RAG (Retrieval-Augmented Generation)**: Architecture supplementing LLM prompts with semantic context retrieved from external vector databases.
* **Default Chatbot**: System-designated assistant automatically made available to authenticated users.