Twilio AI Health Triage is a comprehensive dual-interface healthcare platform that provides both web-based chatbot and SMS communication channels. Tech-savvy users can interact through a modern web interface (currently fastapi chatbot endpoint), while non-technical users can simply communication with AI from their mobile phones via sms. The system combines AI-powered chatbot capabilities with intelligent triage and emergency escalation, seamlessly handling patient inquiries across both channels.

• Tech-Savvy Patients - Web interface with instant chat responses
• Non-Technical Users - Simple SMS texting from any mobile phone
• Healthcare Providers - Streamline patient communication across all channels
• Medical SMBs - Automate appointment booking and basic health queries
• Platform Companies - Integrate health triage into existing systems

• Natural language understanding for medical queries
• Context-aware responses using OpenAI GPT models
• Multi-turn conversation support with session management

• Automatic detection of emergency keywords
• Instant human operator alerts for critical situations
• Customizable escalation rules and triggers

• Conversational appointment scheduling
• Multi-step booking workflow (purpose → patient → date → time → specialist)
• Automated confirmation and reminder system

• Customizable prompts per organization type (SMB, Provider, Platform)
• Organization-specific routing and responses
• White-label ready architecture

• In-memory webhook event logging
• Session tracking and conversation history
• API call monitoring and debugging tools

┌─────────────────┐                           ┌─────────────────────┐
│   Chat API      │-------------------------->│                     │
│  /api/v1/chat   │                           │                     │
└─────────────────┘                           │                     │
                                              │   FastAPI Backend   │
┌─────────────────┐    ┌─────────────────┐    │   (Core Engine)     │
│   Patient SMS   │--->│  Twilio Webhook │--->│                     │
│  (Mobile Phone) │    │/api/v1/chat/send│    │                     │
└─────────────────┘    └─────────────────┘    └─────────────────────┘
                                                         │
                       ┌─────────────────┐               │
                       │ Session Manager │<--------------│
                       │                 │               │
                       │ (Memory/Redis)  │               │
                       └─────────────────┘               │
                                                         │
                       ┌─────────────────┐               │
                       │   OpenAI API    │<--------------│
                       │ (GPT-3.5/4 AI)  │               │
                       └─────────────────┘               │
                                                         │
┌─────────────────┐    ┌─────────────────┐               │
│ Human Escalation│<---│  Triage Engine  │               │
│ (Emergency Ops) │    │ (Keyword Detect)│<--------------│
└─────────────────┘    └─────────────────┘               │
                                                         │
┌─────────────────┐    ┌─────────────────┐               │
│ Appointment Sys │<---│ Booking Engine  │<--------------│         
│ (Calendar/EHR)  │    │(Multi-step Flow)│
└─────────────────┘    └─────────────────┘

• Backend: FastAPI (Python 3.10+)
• AI Engine: OpenAI GPT-3.5/4 with LangChain
• SMS Gateway: Twilio SMS API
• Session Management: In-memory storage (Redis ready)
• Containerization: Docker & Docker Compose
• Reverse Proxy: Nginx

Before you begin, ensure you have:

• Python 3.10+ installed
• Docker & Docker Compose for containerized deployment
• Twilio Account with SMS capabilities
• OpenAI API Key for AI functionality

git clone https://github.com/syeda434am/Twilio-AI-Health-Triage.git
cd Twilio-AI-Health-Triage
cp .env
# Edit .env with your credentials
docker compose up --build

🎉 That's it! Your dual-interface health triage system is now running at:

• Web Chat Interface: http://localhost:5020
• SMS Webhook Endpoint: http://localhost:5020/api/v1/chat/send

1. Clone the repository

   git clone https://github.com/your-org/twilio-ai-health-triage.git
   cd twilio-ai-health-triage

2. Set up environment variables

   cp .env.example .env
   nano .env  # Edit with your credentials

3. Build and run

   docker compose up --build -d

1. Install Python dependencies

   pip install -r requirements.txt

2. Run the FastAPI application

   uvicorn com.mhire.app.main:app --reload --host 0.0.0.0 --port 8000

Create a .env file in the project root:

# OpenAI Configuration
OPENAI_API_KEY=sk-your-openai-api-key-here
OPENAI_MODEL=gpt-3.5-turbo

# Twilio Configuration
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_twilio_auth_token_here
TWILIO_PHONE_NUMBER=+1234567890

# Organization Lookup
PHONE_LOOKUP_ENDPOINT=https://api.yourorg.com/lookup

# Application Settings
DEBUG=false
LOG_LEVEL=INFO

The system supports three organization types with customized prompts:

POST /api/v1/chat
Content-Type: application/json

{
  "message": "I have chest pain and difficulty breathing",
  "organization_type": "PROVIDER",
  "session_id": "web_user_12345"
}

Response:

{
  "response": "This sounds like a medical emergency. I'm connecting you with a healthcare professional immediately.",
  "escalation_type": "EMERGENCY",
  "session_id": "web_user_12345",
  "requires_human": true
}

POST /api/v1/chat/send
Content-Type: application/x-www-form-urlencoded

Body=Hello, I need to book an appointment
From=+1234567890
To=+0987654321
MessageSid=SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

GET /api/v1/webhooks/visit-logged?limit=50

Once running, visit:

• Swagger UI: http://localhost:5020/docs
• ReDoc: http://localhost:5020/redoc

1. Prepare production environment

   # Set production environment variables
   export ENVIRONMENT=production
   export DEBUG=false

2. Deploy with Docker Compose

   docker compose -f docker-compose.prod.yml up -d

3. Configure Twilio Webhook URL

   • Set your Twilio webhook URL to: https://yourdomain.com/api/v1/chat/send
   • Ensure HTTP POST method is selected

• Redis Integration: Replace in-memory sessions with Redis for horizontal scaling
• Database: Add PostgreSQL for persistent conversation history
• Load Balancer: Use multiple FastAPI instances behind a load balancer
• Message Queue: Implement Celery for background task processing

Emergency via Web:

User types in web chat: "Help! I'm having severe chest pain and can't breathe properly!"

System Response (displayed in chat):
🚨 EMERGENCY DETECTED 🚨

This sounds like a medical emergency. I'm immediately 
connecting you with emergency medical services.

Stay calm and call 911 if you haven't already.
A healthcare professional will contact you shortly.

Reference ID: EMRG_20241226_001

Appointment Booking via Web:

User: "I need to book an appointment"
Bot: "I'll help you schedule an appointment. What's the purpose of your visit?"

User: "Annual checkup"
Bot: "Great! What's the patient's name?"

User: "John Smith"
Bot: "Thank you. What date works best for you?"

User: "Next Tuesday"
Bot: "Perfect! What time would you prefer? (Morning/Afternoon/Evening)"

User: "Morning"
Bot: "Excellent! Your appointment is scheduled:
     📅 Date: Tuesday, Jan 2nd, 2024
     ⏰ Time: 9:00 AM
     👤 Patient: John Smith
     📋 Purpose: Annual checkup
     
     You'll receive a confirmation message shortly."

Emergency via SMS:

📱 Patient texts: "Help chest pain bad"

📲 System responds: "🚨 EMERGENCY - This sounds serious. 
Emergency services contacted. Call 911 now if you haven't. 
Stay calm. Help is coming. Ref: EMRG_001"

Appointment via SMS:

📱 "book appointment"
📲 "I'll help you schedule. What's the visit for?"

📱 "checkup"  
📲 "Great! Patient name?"

📱 "John Smith"
📲 "Thanks! Preferred date?"

📱 "next tuesday"
📲 "Time preference? Reply: 1-Morning, 2-Afternoon, 3-Evening"

📱 "1"
📲 "✅ Booked! Tue Jan 2, 9AM for John Smith (checkup). 
Confirmation coming via SMS."

Patient Input:

"What should I do about a persistent headache?"

System Response:

For persistent headaches, here are some general recommendations:

💊 Immediate relief:
- Stay hydrated
- Rest in a quiet, dark room
- Consider over-the-counter pain relievers

⚠️ See a doctor if you experience:
- Sudden, severe headaches
- Headaches with fever or neck stiffness
- Vision changes or confusion

Would you like to schedule an appointment for evaluation?

twilio-ai-health-triage/
├── 📁 com/mhire/app/
│   ├── 🐍 main.py                    # FastAPI application entry point
│   ├── 📁 config/                    # Configuration management
│   ├── 📁 common/                    # Shared utilities and responses
│   └── 📁 services/
│       ├── 📁 chatbot_services/      # AI chatbot logic
│       │   ├── 🤖 ai_chatbot.py      # Core AI functionality
│       │   ├── 📋 session_manager.py # Session tracking
│       │   ├── 📅 appointment_booking.py # Booking workflows
│       │   ├── 🚨 escalation_dictionary.py # Emergency keywords
│       │   └── 💬 prompt_dictionary.py # AI prompts
│       └── 📁 twilio_services/       # Twilio integration
│           ├── 📱 twilio_inbound.py  # SMS webhook handling
│           └── 📊 webhook_log_manager.py # Logging system
├── 📁 nginx/
│   └── ⚙️ nginx.conf                 # Reverse proxy configuration
├── 🐳 Dockerfile                     # Container definition
├── 🐙 compose.yaml                   # Docker Compose setup
├── 📋 requirements.txt               # Python dependencies
├── 🔧 .env.example                   # Environment template
└── 📖 README.md                      # This file

We welcome contributions! Here's how to get started:

1. Fork and clone the repository

   git clone https://github.com/your-username/twilio-ai-health-triage.git
   cd twilio-ai-health-triage

2. Create a virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt
   pip install -r requirements-dev.txt  # Development dependencies

4. Run tests

   pytest tests/

• 🐛 Bug Reports: Use GitHub Issues with detailed reproduction steps
• ✨ Feature Requests: Propose new features with use cases and examples
• 🔧 Code Style: Follow PEP 8 and use Black for formatting
• ✅ Testing: Add tests for new features and bug fixes
• 📝 Documentation: Update README and docstrings for changes

1. Create a feature branch: git checkout -b feature/your-feature-name
2. Make your changes with tests
3. Run the test suite: pytest
4. Update documentation if needed
5. Submit a pull request with a clear description

• No Persistent Storage: Conversations are stored in-memory only
• Session Security: Session IDs are generated securely
• API Key Protection: Environment variables for sensitive data
• HIPAA Considerations: Designed with healthcare privacy in mind

• Immediate Escalation: Critical keywords trigger instant human alerts
• Audit Trail: All emergency escalations are logged with timestamps
• Failsafe Mechanisms: System defaults to human escalation on uncertainty

• Webhook Events: All Twilio interactions logged
• AI Conversations: Chat sessions tracked with metadata
• Error Tracking: Comprehensive error logging and handling

• Prometheus Metrics: Add /metrics endpoint for monitoring
• Health Checks: Built-in health check endpoints
• Performance Monitoring: Request timing and response metrics

# Check webhook URL configuration
curl -X POST http://localhost:5020/api/v1/chat/send \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "Body=test&From=+1234567890&To=+0987654321"

# Verify API key
export OPENAI_API_KEY=your_key_here
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
  https://api.openai.com/v1/models

# Clean build
docker compose down
docker system prune -f
docker compose up --build --force-recreate

This project is licensed under the MIT License - see the LICENSE file for details.

Special thanks to the amazing technologies and communities that make this project possible:

• Twilio - Reliable SMS infrastructure
• OpenAI - Powerful AI language models
• FastAPI - Modern, fast web framework
• LangChain - AI application development framework
• Docker - Containerization platform