How SmartBot processes requests
Understand how SmartBot receives, validates, and routes incoming guest messages from the web chat widget and SMS channels before generating a response.
Audience: Administrators and technical users who want to understand SmartBot's request processing pipeline.
Before you begin
- No configuration is required to use this article. It explains how SmartBot works internally so you can better diagnose issues and understand system behavior.
How request processing works
Channel detection
When a guest sends a message to SmartBot, the system first determines which channel the message came from:
- SMS β Detected by the presence of a Twilio signature header in the request.
- Web chat β Detected by the presence of a connection identifier in the request.
Each channel has its own processing path and session format.
Validation checks
Before creating or updating a conversation session, SmartBot performs several validation checks:
- Phone number validation β For SMS, the guest's phone number is validated and normalized. Invalid phone numbers are rejected.
- Organization and center lookup β For SMS, SmartBot identifies the organization and center by matching the bot's phone number against provisioned phone numbers.
- Blacklist check β SmartBot checks whether the guest's phone number has been blocked. Blacklisted numbers are silently ignored with no response sent.
- Active status check β SmartBot verifies that both the organization and center are active. Messages to inactive organizations or centers are rejected.
Session management
SmartBot maintains a conversation session for each guest interaction. Sessions are identified by a unique session ID and have a 30-minute expiry window:
- New conversations β A new session is created for first-time interactions or after a previous session has expired.
- Returning guests β If a session exists and has not expired, the existing session is updated with the new message.
- Session rollover β When a session has the rollover flag set, a new session ID is created while preserving the organization, center, and channel context.
Sessions track the guest's identity, the current conversation state, and references to business configuration needed to generate responses.
Throttling
If a guest sends a message while SmartBot is still processing their previous message, the system holds the new message and sends a brief acknowledgment. This prevents out-of-order responses and ensures conversations remain coherent.
Business configuration loading
For each new session, SmartBot fetches the business configuration needed to generate appropriate responses. This includes:
- Organization labels for guests and providers.
- Prompt templates for the organization and center.
- Bot settings and appearance configuration.
- Center booking and operational settings.
- Core organizational settings.
Handoff to agent orchestration
Once validation passes and the session is ready, SmartBot passes the session to the agent orchestration layer, which classifies the guest's intent and routes to the appropriate AI agent.