Chatbot & AI Automation Setup Guide

Comprehensive operational and architectural guide to managing global tenant automation killswitches, AI fallback engines, operating schedules, and live-chat handoff rules in SMSPort.

🧭 Executive Overview

The Chatbot and AI Setup console (/setup/chatbot-ai) acts as the master switchboard for your organization's messaging infrastructure. While the Visual Bot Builder V2 is where you design conversation flows and the Live Chat Console is where human agents talk to customers, this settings surface controls the global policy rules that govern how and when automations are allowed to execute.

🗺️ Inbound Message Evaluation Lifecycle

Whenever an incoming message arrives from a customer across your WhatsApp Senders or other channels, SMSPort evaluates it through the following pipeline:

graph TD
    A[Customer Inbound Message] --> B{Chatbot Master Switch?}
    B -->|Disabled| H[Direct to Human Agent Queue]
    B -->|Enabled| C{Inside Allowed Operating Hours?}
    C -->|Outside Hours| I[Silent / Off-Hours Queue]
    C -->|Inside Hours| D{Human Presence Lock Active?}
    D -->|Locked 30m| H
    D -->|Unlocked| E{Visual Flow Trigger Matched?}
    E -->|Yes: Keyword/Flow Match| F[Execute Visual Bot Flow]
    E -->|No Match| G{AI Fallback Enabled?}
    G -->|Disabled: Manual Only| H
    G -->|Enabled: Auto Reply| J[LLM Generative Response]
    G -->|Enabled: Suggest Reply| K[Draft Saved to Live Chat Copilot]

🎛️ Core Automation Switches (Deep Dive)

The Core Switches tab contains the fundamental toggles governing tenant-wide behavior.

1. Chatbot (Global Master Killswitch)

• Purpose: Serves as the primary circuit breaker for all automated conversation engines.
• Options: Enabled | Disabled

[!TIP]
When to use Disabled: Use this as an emergency killswitch during major system maintenance, PR crises, unexpected flow misconfigurations, or holiday office closures where all messages must be triaged manually by humans.

2. AI (Generative Brain Switch)

• Purpose: Dictates whether Large Language Models (LLMs) are authorized to assist with incoming conversations.
• Options: Enabled | Disabled

3. Mode (AI Execution Strategy)

• Purpose: Controls whether AI operates as an autonomous agent or as an assistant to human operators.
• Options: Disabled | Suggest reply | Auto reply

A. `Disabled`

AI generative capability is completely deactivated. If a customer's message fails to trigger an existing bot flow, the conversation falls back immediately to the queue without any AI processing.

B. `Suggest reply` *(Agent Copilot Mode)*

• How it works: When a customer sends a message that warrants an AI reply, the AI engine drafts a suggested response in the background.
• Safety: The suggested reply is NEVER sent directly to the customer. Instead, it appears in a dedicated copilot drawer inside the Live Chat Console.
• Human in the Loop: A human agent can inspect the AI-generated draft, edit clinical or pricing details, and click Send. This provides maximum quality assurance for healthcare, financial, and high-compliance workflows.

C. `Auto reply` *(Autonomous Bot Mode)*

• How it works: When no rule-based flow matches, the AI engine directly formats and dispatches the response back to the customer's WhatsApp without human intervention.
• Requirements: Requires a well-defined System Prompt and Assistant Tone configured in the AI Brain settings to ensure responses adhere to corporate guardrails.

4. Human Handoff (Presence Lock)

• Purpose: Prevents bots from interrupting human conversations.
• Options: Enabled | Disabled

⏰ Operating Schedule & Active Windows

The Operating Schedule tab allows you to constrain automated message delivery to specific daily business hours.

1. Rule-Based Chatbot Window (`Chatbot from` / `Chatbot to`)

• Defines the daily time window (in local timezone) during which standard rule-based bot flows are permitted to reply.
• Example: 09:00 to 18:00.
• Behavior: Outside these hours, inbound messages do not trigger automated flows, preventing late-night bot notifications from disturbing patients.
• 24/7 Operation: Leave both fields blank to allow bots to run 24 hours a day, 7 days a week.

2. AI Generative Window (`AI from` / `AI to`)

• Restricts expensive or autonomous generative AI operations to supervised time windows (e.g., when senior clinical or support staff are on shift to monitor outputs).
• 24/7 Operation: Leave both fields blank for continuous AI availability.

🧠 Advanced & AI Brain Configuration

The Advanced & AI Brain tab houses the model parameters, system prompt engineering, and fallback routing.

1. AI Provider

• Mock (Simulator): Built-in test sandbox that produces instant deterministic mock replies without requiring third-party API keys. Ideal for local testing and CI/CD pipelines.
• OpenAI Compatible: Connects to any standard OpenAI-compliant REST endpoint (OpenAI ChatGPT, Azure OpenAI, DeepSeek, Anthropic via gateway, Google Gemini via proxy).

2. Fallback Behavior

Dictates what happens when a customer sends a free-form question that matches no keyword, intent, or button in your Visual Bot Builder:

• Manual only (Queue): Halts automation and flags the conversation as unassigned in the Live Chat Console with an "Unmatched Intent" label.
• Handoff to AI: Passes the customer's query, chat history, and your System Prompt to the configured AI model to attempt a contextual answer.

3. Model Identifier (`AI model`)

Specifies the exact model slug dispatched in the API payload:

• gpt-4o-mini: High-speed, cost-effective baseline.
• gpt-4o: Complex multi-step reasoning and clinical analysis.
• deepseek-chat: High-density multi-lingual reasoning.

4. Assistant Tone & System Prompt

• Assistant Tone: Guiding stylistic adjectives (e.g., empathetic, professional, concise, clinical).
• System Prompt: Master instructions prepended to every conversation. Include:
  1. Organization name and core mission.
  2. Operating policies and disclaimers (e.g. "Always advise seeking emergency care for acute chest pain").
  3. Escalation triggers that should immediately recommend human staff.

5. Feature Flags JSON

A raw JSON dictionary for runtime experimentation and beta switches:

{
  "pilot": true,
  "streamResponses": false,
  "strictClinicalGuardrails": true
}

🔗 Related Documentation & Resources

• Visual Bot Builder V2 Tutorial — Build your first interactive flow.
• Built-in Nodes Reference — Complete list of all 22+ execution nodes.
• AI Clinical Agent Node — Deploying conversational medical assistants.
• Human Handoff Node — Configuring queue priorities and team routing.
• Integrations Hub — Connect Google Sheets, Webhooks, and EMR databases.
• WhatsApp Cloud API Senders — Manage your official Meta Business phone numbers.