🤖 What is SNIKO Conversational AI?

Imagine having a smart assistant that can talk to your customers 24/7, schedule appointments, conduct surveys, and handle phone calls — all without you being there. That's exactly what SNIKO Conversational AI does for your business!

What Can SNIKO Do For Your Business?

🚀 Installation & Setup

This section covers the complete installation and setup process for SNIKO Conversational AI. Follow these steps to get your system up and running.

📋 Prerequisites

🔧 Installation Steps

1. Clone the Repository

   git clone https://github.com/your-repo/snak-conversational-ai.git
   cd snak-conversational-ai

2. Install PHP Dependencies

   composer install

3. Install Node.js Dependencies

   npm install

4. Setup Environment File

   cp .env.example .env
   php artisan key:generate

5. Configure Database

   Edit your .env file with database credentials:

   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=snak_ai
   DB_USERNAME=your_username
   DB_PASSWORD=your_password

6. Run Database Migrations

   php artisan migrate --seed

7. Build Frontend Assets

   npm run build

8. Setup MCP Server

   cd mcp-servers/unified
   npm install

🎯 Quick Installation Script

For Windows users, you can use the provided PowerShell scripts:

# Complete system startup
./start-complete-system.ps1

# Individual components
./start-laravel.bat      # Laravel development server
./start-mcp-server.bat   # MCP server
./start-tunnel.bat       # LocalTunnel for webhooks

⚙️ System Requirements

Detailed system requirements for optimal performance of SNIKO Conversational AI.

🖥️ Server Requirements

📚 Required PHP Extensions

Note: The installer checks for PHP 8.4.0+ specifically, though composer allows 8.2+

• bcmath - Arbitrary precision mathematics
• ctype - Character type checking
• curl - HTTP client library
• dom - Document Object Model
• fileinfo - File information
• json - JSON parsing
• mbstring - Multibyte string handling
• openssl - Cryptographic functions
• pcre - Perl-compatible regular expressions
• pdo - PHP Data Objects
• tokenizer - PHP tokenizer
• xml - XML parsing
• zip - Archive handling

🔌 External Service Dependencies

🏃 Quick Start Guide

Get SNIKO running in 5 minutes with this streamlined setup process.

⚡ Express Setup (Web Installer)

1. Access Web Installer

   Navigate to https://your-domain.com/installer to launch the guided installer.

2. System Requirements Check

   Installer validates PHP version (8.4.0+), extensions, and file permissions.

3. License Verification

   Enter your license key to verify and activate the system.

4. Database Configuration

   Configure database connection, test connectivity, and run migrations.

5. Admin Account Creation

   Create your administrator account with full system access.

6. Configuration Complete

   System is ready - configure additional services through admin panel.

🛠️ Command Line Setup (Advanced)

# Generate application key
php artisan key:generate

# Run database migrations
php artisan migrate --seed

# Create admin user via command
php artisan make:admin

# Setup ElevenLabs integration
php artisan setup:elevenlabs

# Configure Twilio softphone
php artisan softphone:complete-setup

🔧 Essential Configuration Steps

✅ Verification Checklist

After setup, verify these components are working:

• ✅ Web Application: Dashboard loads at http://localhost:8000
• ✅ MCP Server: Health check at http://localhost:3001/health
• ✅ Database Connection: Test in Admin → System Config
• ✅ ElevenLabs API: Test connection in Admin panel
• ✅ Twilio API: Test softphone functionality

🚀 Getting Started

Welcome to SNIKO! This guide will walk you through everything you need to know to get up and running quickly.

Step 1: Logging In

Step 2: First Steps

Once you're logged in, here's what to do first:

• Explore Your Dashboard: Get familiar with the main interface
• Check Your Profile: Make sure your information is correct
• Look at Available Features: See what tools you have access to
• Explore Voices: If you want to see what voices are available

📊 Understanding Your Dashboard

Your dashboard is like the control center of your business. It shows you everything that's happening and gives you quick access to all the tools you need.

What You'll See on Your Dashboard

Quick Actions

From your dashboard, you can quickly:

• Create a new AI agent
• Set up an appointment system
• Create a survey
• Check your billing status
• View conversation history

🤖 Creating Your First AI Agent

An AI agent is like a virtual employee that can talk to your customers. Let's create your first one!

What is an AI Agent?

Step-by-Step Agent Creation

1. Go to "Agents" in your dashboard
2. Click "Create New Agent"
3. Give your agent a name (like "Customer Service Sarah")
4. Write instructions for your agent - tell it what to do and how to behave
5. Choose a voice from the available options
6. Test your agent by having a conversation with it
7. Save and activate your agent

Writing Good Instructions

Your agent needs clear instructions to work well. Here's what to include:

• Your business information: Hours, location, services
• How to greet customers: Friendly, professional tone
• What questions to ask: To understand what customers need
• How to handle common requests: Appointments, questions, problems
• When to transfer to a human: For complex issues

🎭 Working with Voices

Voices make your AI agents sound like real people. You can choose from many different voices or even create your own!

What are Voices?

Choosing the Right Voice

Creating Custom Voices

You can create your own unique voice by:

1. Recording sample audio (your own voice or someone else's)
2. Uploading the audio to SNIKO
3. AI will generate several options
4. Choose your favorite and save it

💬 How Conversations Work

Understanding how your AI agents have conversations with customers is key to getting the most out of SNIKO. Let's break down exactly how this magic happens!

What Happens During a Conversation?

The Conversation Flow

Types of Conversations

📞 Phone Conversations: Voice-to-voice with call controls and recording

💬 Text Conversations: Chat, SMS, WhatsApp with emoji and file support

📧 Email Conversations: Rich formatting with attachments and sequences

What Your Agent Can Do

• Answer Questions: About your business, products, policies, technical support
• Book Appointments: Check availability, suggest times, confirm details
• Conduct Surveys: Ask questions, record responses, follow up
• Process Orders: Product recommendations, pricing, payment collection

Real-World Conversation Examples

🌍 Environment Setup

Configure your environment variables for optimal SNIKO performance. All configuration is managed through the .env file and admin panel.

📋 Core Environment Variables

🔧 Application Settings

# Application Configuration
APP_NAME="SNIKO Conversational AI"
APP_ENV=production
APP_KEY=base64:your_generated_key
APP_DEBUG=false
APP_URL=https://your-domain.com

🗄️ Database Configuration

# Database Settings
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=snak_ai
DB_USERNAME=your_db_user
DB_PASSWORD=your_secure_password

📧 Email/SMTP Settings

# Email Configuration
MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
[email protected]
MAIL_PASSWORD=your_app_password
MAIL_ENCRYPTION=tls
[email protected]
MAIL_FROM_NAME="${APP_NAME}"

🎤 ElevenLabs Configuration

# ElevenLabs API Settings
ELEVENLABS_API_KEY=sk_your_32_character_api_key
ELEVENLABS_TOOL_WEBHOOK_SECRET=your_webhook_secret

📞 Twilio Configuration

# Twilio Settings
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_FROM_NUMBER=+1234567890
TWILIO_MESSAGING_SERVICE_SID=MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Softphone-specific
TWILIO_API_KEY=SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_API_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_TWIML_APP_SID=APxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_PHONE_NUMBER=+1234567890

💳 Stripe Payment Configuration

# Stripe Settings
PAYMENT_ENVIRONMENT=sandbox  # or 'live'

# Test Keys
STRIPE_TEST_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxxxxxxxxx
STRIPE_TEST_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxx
STRIPE_TEST_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxx

# Live Keys (Production Only)
STRIPE_LIVE_PUBLISHABLE_KEY=pk_live_xxxxxxxxxxxxxxxxxx
STRIPE_LIVE_SECRET_KEY=sk_live_xxxxxxxxxxxxxxxxxx
STRIPE_LIVE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxx

🗄️ Database Configuration

Set up and manage your database for optimal performance and reliability.

🔧 Supported Database Systems

⚡ Database Setup Commands

# Create database
mysql -u root -p
CREATE DATABASE snak_ai CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'snak_user'@'localhost' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON snak_ai.* TO 'snak_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

# Run migrations
php artisan migrate --seed

📊 Database Performance Optimization

# Add to my.cnf or my.ini
[mysqld]
innodb_buffer_pool_size = 1G
max_connections = 200
query_cache_type = 1
query_cache_size = 64M
tmp_table_size = 64M
max_heap_table_size = 64M

🔒 Database Security

• Use Strong Passwords: Minimum 16 characters with mixed case, numbers, symbols
• Limit User Privileges: Grant only necessary permissions
• Enable SSL: Encrypt database connections
• Regular Backups: Automated daily backups with retention
• Monitor Access: Log and review database access patterns

🎤 ElevenLabs Integration

Configure ElevenLabs for AI voice synthesis and conversational capabilities.

🔑 Getting Your ElevenLabs API Key

1. Visit elevenlabs.io
2. Create an account or sign in
3. Navigate to your profile settings
4. Find the API section
5. Copy your API key (starts with sk_)

⚙️ Configuration Methods

Method 1: Artisan Command (Recommended)

# Interactive setup
php artisan setup:elevenlabs

# Non-interactive with key  
php artisan setup:elevenlabs --key=sk_your_api_key

Method 2: Admin Panel

1. Login to admin panel
2. Go to Admin → System Config
3. Find ElevenLabs section
4. Enter your API key
5. Click "Test ElevenLabs" to verify
6. Save configuration

Method 3: Manual Environment

# Add to .env file
ELEVENLABS_API_KEY=sk_your_32_character_api_key

🧪 Testing Your Setup

# Test API connection (via console command)
php artisan test:elevenlabs

# Sync available voices from ElevenLabs API
php artisan elevenlabs:sync

# Test API connectivity directly
curl -H "xi-api-key: your_api_key" https://api.elevenlabs.io/v1/user

🔧 ElevenLabs Features Configuration

⚠️ Common Issues & Solutions

📞 Twilio Softphone Setup

Configure Twilio for phone calls, SMS messaging, and softphone capabilities.

🚀 Quick Setup with Zero-Touch Configuration

# Interactive setup with prompts
php artisan softphone:complete-setup

# Automated setup (no prompts)
php artisan softphone:complete-setup \
  --sid=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --phone=+15551234567 \
  --auto

📋 Manual Configuration Steps

1. Get Twilio Credentials

1. Sign up at twilio.com
2. Get your Account SID and Auth Token from the console
3. Purchase a phone number (or use trial number)
4. Create TwiML App for softphone
5. Generate API Key and Secret

2. Environment Configuration

# Basic Twilio Settings
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_FROM_NUMBER=+1234567890

# SMS Configuration
TWILIO_MESSAGING_SERVICE_SID=MGxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SMS_DEFAULT=twilio
SMS_TWILIO_ENABLED=true

# Softphone Configuration
TWILIO_API_KEY=SKxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_API_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_TWIML_APP_SID=APxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_PHONE_NUMBER=+1234567890

3. Webhook Configuration

Configure these webhook URLs in your TwiML App:

# Voice Webhook URLs (automatically configured by setup command)
Voice Request URL: https://your-domain.com/softphone/voice
Voice Status Callback: https://your-domain.com/softphone/status
Fallback URL: https://your-domain.com/softphone/fallback

🧪 Testing Softphone Functionality

# Check setup status
php artisan softphone:setup

# Test configuration
php artisan softphone:test

# Generate access tokens for testing
php artisan softphone:token --identity=test_user

📞 Available Features After Setup

🔧 Advanced Configuration

🔗 MCP Server Setup

Configure the Model Context Protocol server for AI agent tool integrations and external API communications.

🏗️ MCP Architecture Overview

🚀 Starting the MCP Server

Method 1: Individual Setup

# Navigate to MCP server directory
cd mcp-servers/unified

# Install dependencies
npm install

# Build TypeScript files
npm run build

# Start the server (uses server-inspector.js)
npm run start

# Development mode with auto-restart (uses server-inspector.ts)
npm run dev

Method 2: Batch Scripts (Windows)

# Start individual components
start-mcp-server.bat     # MCP server only
start-laravel.bat        # Laravel server only
start-tunnel.bat         # LocalTunnel only

# Start complete system
start-complete-system.ps1

🔍 MCP Server Endpoints

🔧 Tool Configuration

Appointment Tools

• check_availability - Check available appointment slots
• book_appointment - Create new appointments
• cancel_appointment - Cancel existing appointments

Survey Tools

• create_survey - Generate new customer surveys
• get_survey - Retrieve survey data and responses

🔗 ElevenLabs Integration

Configure ElevenLabs agents to use MCP tools:

# MCP Connection URL for ElevenLabs
http://localhost:3001/mcp

# With tunnel for external access
https://your-tunnel-url.loca.lt/mcp

📊 Monitoring & Debugging

# Check server logs
npm run logs

# Monitor performance
curl http://localhost:3001/health

# Debug specific tools
curl http://localhost:3001/appointment/debug

🛠️ Adding Custom Tools

🛠️ ElevenLabs Tool Generator

Use the built-in tool generator for rapid development:

# Generate complete ElevenLabs tool boilerplate
php artisan make:elevenlabs-tool YourToolName \
  --description="Description of your tool" \
  --with-frontend \
  --with-tests \
  --with-migration

# Register SMS tool with ElevenLabs
php artisan elevenlabs:register-sms

# Manage existing tools
php artisan elevenlabs:register-sms list

💳 Stripe Payment Configuration

Set up Stripe for secure payment processing and subscription management.

🏦 Stripe Account Setup

1. Create account at stripe.com
2. Complete business verification
3. Get your API keys from the Stripe Dashboard
4. Configure webhooks for real-time events

🔑 API Keys Configuration

Test Environment (Sandbox)

# Test Keys (for development)
PAYMENT_ENVIRONMENT=sandbox
STRIPE_TEST_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxxxxxxxxxxx
STRIPE_TEST_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxx
STRIPE_TEST_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxx

Live Environment (Production)

# Live Keys (for production)
PAYMENT_ENVIRONMENT=live
STRIPE_LIVE_PUBLISHABLE_KEY=pk_live_xxxxxxxxxxxxxxxxxxxx
STRIPE_LIVE_SECRET_KEY=sk_live_xxxxxxxxxxxxxxxxxxxx
STRIPE_LIVE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxx

⚙️ Configuration Methods

Method 1: Admin Panel (Recommended)

1. Login to admin panel
2. Navigate to Admin → System Config
3. Find Stripe Configuration section
4. Select environment (sandbox/live)
5. Enter your API keys
6. Click "Test Stripe" to verify
7. Save configuration

Method 2: Environment File

Add the keys directly to your .env file using the format above.

🔗 Webhook Configuration

Webhook URL: https://your-domain.com/stripe/webhook

🧪 Testing Payment Integration

# Test Stripe connection via admin panel
Admin → System Config → Test Stripe

# Use Stripe test card numbers
4242424242424242  # Visa
4000000000003220  # 3D Secure
4000000000000002  # Declined

💼 Subscription Plans Configuration

🔒 Security Best Practices

• Use HTTPS: Always encrypt payment data in transit
• Webhook Verification: Verify webhook signatures
• Key Management: Rotate keys regularly
• Environment Separation: Keep test and live keys separate
• Access Control: Limit who can access API keys

📅 Setting Up Appointments

Let your customers book appointments with you automatically! Your AI agent can handle the entire booking process.

What are Appointments in SNIKO?

Step-by-Step Appointment Setup

1. Go to "Appointments" in your dashboard
2. Set your availability - when you're available for appointments
3. Choose appointment types - consultation, follow-up, etc.
4. Set duration - how long each appointment should be
5. Add buffer time - time between appointments
6. Test the system - try booking an appointment yourself

Appointment Features

Appointment Types You Can Set Up

• Consultations: Initial meetings with new clients
• Follow-ups: Check-in appointments
• Service Appointments: Specific services you offer
• Group Sessions: Multiple people at once
• Virtual Meetings: Online appointments

📊 Creating Surveys

Collect feedback from your customers automatically! Create surveys that your AI agents can conduct during conversations.

What are Surveys in SNIKO?

Step-by-Step Survey Creation

1. Go to "Surveys" in your dashboard
2. Click "Create New Survey"
3. Give your survey a title (like "Customer Satisfaction Survey")
4. Add your questions - multiple choice, rating scales, or open-ended
5. Set when to conduct the survey - after appointments, randomly, etc.
6. Test your survey - try it out yourself first
7. Activate your survey - start collecting responses

Survey Question Types

When to Use Surveys

• After Appointments: Get feedback on the service provided
• Customer Satisfaction: Regular check-ins with customers
• Market Research: Understand what customers want
• Product Feedback: Learn about new products or services
• Service Improvement: Identify areas to improve

📞 Communication Tools

SNIKO includes powerful communication tools to help you connect with customers through multiple channels.

📱 SMS Messaging

📧 Email Automation

Send automated emails to customers based on their interactions:

• Appointment confirmations
• Follow-up messages
• Survey invitations
• Thank you notes
• Reminder messages
• Promotional content

💬 WhatsApp Integration

Connect with customers through WhatsApp Business:

• Send messages and media
• Receive customer messages
• Automated responses
• Rich message formatting
• File sharing
• Location sharing

🌐 Website Chat

Add a chat widget to your website:

• Instant customer support
• Lead capture
• FAQ automation
• Appointment booking
• Customizable appearance

Setting Up Communication Channels

📱 SMS Integration

Configure SMS messaging for customer communication and AI agent interactions.

🔧 SMS Provider Setup

⚙️ Configuration Steps

1. Twilio SMS Configuration

# Add to .env file
SMS_DEFAULT=twilio
SMS_TWILIO_ENABLED=true

# Use Messaging Service (Recommended)
TWILIO_MESSAGING_SERVICE_SID=MGxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Or use specific phone number
TWILIO_FROM_NUMBER=+1234567890

2. ElevenLabs SMS Tool Setup

# Add webhook secret for security
ELEVENLABS_TOOL_WEBHOOK_SECRET=your_shared_secret_here

🤖 ElevenLabs SMS Tool Integration

Configure your ElevenLabs agents to send SMS messages:

{
  "name": "send_sms",
  "type": "client_tool",
  "description": "Send SMS messages to phone numbers in E.164 format",
  "http": {
    "method": "POST",
    "url": "https://your-domain.com/tools/sms"
  },
  "input_schema": {
    "type": "object",
    "required": ["to", "body"],
    "properties": {
      "to": {
        "type": "string",
        "description": "E.164 phone number (e.g., +1234567890)"
      },
      "body": {
        "type": "string",
        "maxLength": 1600,
        "description": "SMS message content"
      },
      "provider": {
        "type": "string",
        "description": "SMS provider (twilio)",
        "enum": ["twilio"]
      }
    }
  }
}

📲 SMS Features & Capabilities

🧪 Testing SMS Integration

# Test SMS sending via admin panel
Admin → Communication → Test SMS

# Test via API endpoint
curl -X POST https://your-domain.com/tools/sms \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1234567890",
    "body": "Test message from SNIKO",
    "provider": "twilio"
  }'

📋 SMS Use Cases

• Appointment Confirmations: Automated booking confirmations
• Reminders: Upcoming appointment or payment reminders
• Customer Support: Quick responses to customer inquiries
• Surveys: Post-service feedback collection
• Notifications: Status updates and alerts

📧 Email Automation

Configure automated email systems for customer communication and system notifications.

📮 SMTP Configuration

Popular Email Providers

MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls

MAIL_HOST=smtp.office365.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls

MAIL_HOST=smtp.sendgrid.net
MAIL_PORT=587
MAIL_ENCRYPTION=tls

MAIL_HOST=smtp.mailgun.org
MAIL_PORT=587
MAIL_ENCRYPTION=tls

⚙️ Email Configuration Methods

Method 1: Admin Panel (Recommended)

1. Go to Admin → System Config
2. Find SMTP Configuration section
3. Enter your email server details
4. Click "Test SMTP" to verify
5. Save configuration

Method 2: Environment Variables

# Complete SMTP Configuration
MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
[email protected]
MAIL_PASSWORD=your_app_password
MAIL_ENCRYPTION=tls
[email protected]
MAIL_FROM_NAME="${APP_NAME}"

🤖 ElevenLabs Email Tool

Configure AI agents to send emails:

{
  "name": "send_email",
  "type": "client_tool",
  "description": "Send email messages to customers",
  "http": {
    "method": "POST",
    "url": "https://your-domain.com/tools/email"
  },
  "input_schema": {
    "type": "object",
    "required": ["to", "subject", "body"],
    "properties": {
      "to": {
        "type": "string",
        "description": "Recipient email address"
      },
      "subject": {
        "type": "string",
        "description": "Email subject line"
      },
      "body": {
        "type": "string",
        "description": "Email content (HTML supported)"
      },
      "from_name": {
        "type": "string",
        "description": "Sender name (optional)"
      }
    }
  }
}

📬 Automated Email Types

🎨 Email Templates

SNIKO includes professional email templates for:

• Welcome Emails: New user onboarding
• Appointment Confirmations: Booking details and calendar links
• Password Resets: Secure account recovery
• Payment Receipts: Transaction confirmations
• System Notifications: Important updates and alerts

🧪 Testing Email Configuration

# Test via admin panel
Admin → System Config → Test SMTP

# Send test email to verify setup
Test email will be sent to specified address

🔗 Webhooks & APIs

Configure webhooks and API integrations for real-time data synchronization and external service communication.

🎣 Webhook Configuration

ElevenLabs Webhooks

# Webhook Endpoints
Conversation Events: https://your-domain.com/webhooks/elevenlabs/conversation
Agent Events: https://your-domain.com/webhooks/elevenlabs/agent
Tool Responses: https://your-domain.com/tools/sms
Tool Responses: https://your-domain.com/tools/email

Twilio Webhooks

# TwiML Application Webhooks
Voice Request: https://your-domain.com/softphone/voice
Status Callback: https://your-domain.com/softphone/status
SMS Webhooks: https://your-domain.com/webhooks/twilio/sms

Stripe Webhooks

# Payment Events
Webhook Endpoint: https://your-domain.com/stripe/webhook
Events: payment_intent.succeeded, invoice.payment_failed, etc.

🔐 Webhook Security

Environment Variables for Security

# Webhook Secrets
ELEVENLABS_TOOL_WEBHOOK_SECRET=your_elevenlabs_secret
TWILIO_AUTH_TOKEN=your_twilio_token  # Used for verification
STRIPE_WEBHOOK_SECRET=whsec_your_stripe_secret

Signature Verification

SNIKO automatically verifies webhook signatures for:

• ElevenLabs: HMAC-SHA256 signature verification
• Twilio: X-Twilio-Signature validation
• Stripe: Stripe-Signature header verification

📡 API Endpoints

Public API Endpoints (No Auth Required)

# ElevenLabs Tool Endpoints
POST /tools/sms           # Send SMS messages
POST /tools/email         # Send email messages
POST /tools/appointment   # Appointment management
POST /tools/survey        # Survey operations

Authenticated API Endpoints

# Admin API (Requires Authentication)
GET  /api/users          # User management
POST /api/agents         # AI agent creation
GET  /api/conversations  # Conversation history
POST /api/appointments   # Appointment booking

🔑 API Authentication

Session-based Authentication

For web application access using Laravel Sanctum:

# Login to get session
POST /login
{
  "email": "[email protected]",
  "password": "password"
}

Tool Authentication

ElevenLabs tools use webhook secret verification:

# Headers required for tool endpoints
X-Webhook-Signature: sha256=computed_signature
Content-Type: application/json

📊 API Response Format

{
  "success": true,
  "data": {
    // Response data
  },
  "message": "Operation completed successfully",
  "timestamp": "2025-01-08T12:00:00Z"
}

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input parameters",
    "details": {
      "field": "email is required"
    }
  },
  "timestamp": "2025-01-08T12:00:00Z"
}

🧪 Testing Webhooks

# Use ngrok or LocalTunnel for local testing
npm install -g localtunnel
lt --port 8000 --subdomain your-app

# Test webhook endpoints
curl -X POST https://your-tunnel.loca.lt/webhooks/test \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'

👥 User Management

Manage users, roles, and permissions within the SNIKO system.

🔐 User Roles & Permissions

➕ Creating Users

Via Admin Panel

1. Navigate to Admin → Users
2. Click "Create New User"
3. Fill in user details
4. Assign roles and permissions
5. Send invitation email (optional)

Via Command Line

# Create admin user
php artisan make:admin

# Create regular user
php artisan make:user \
  --name="John Doe" \
  --email="[email protected]" \
  --password="secure_password"

🔄 User Account Management

• Profile Updates: Users can update their own information
• Password Changes: Secure password reset functionality
• Email Verification: Required for new accounts
• Two-Factor Auth: Optional security enhancement
• Session Management: View and revoke active sessions

🎭 Role-Based Access Control

📊 User Analytics

Track user activity and engagement:

• Login frequency and patterns
• Feature usage statistics
• API usage and quotas
• Conversation volumes
• Appointment bookings

⚙️ System Configuration

Comprehensive system configuration management through the admin panel.

🎛️ Configuration Categories

📱 Application Settings

• App Name: System branding and titles
• App URL: Base URL for the application
• Environment: local, staging, or production
• Debug Mode: Enable/disable debug information

🗄️ Database Settings

• Host & Port: Database server connection
• Database Name: Target database
• Credentials: Username and password
• Connection Test: Verify database connectivity

📧 SMTP Configuration

• Mail Server: SMTP host and port
• Authentication: Username and password
• From Address: Default sender information
• Email Test: Send test email to verify setup

💳 Payment Processing

• Environment: Sandbox or live payment processing
• API Keys: Test and live Stripe keys
• Webhook Secrets: Secure webhook verification
• Connection Test: Verify Stripe API access

🎤 ElevenLabs Integration

• API Key: ElevenLabs service authentication
• Webhook Secret: Tool integration security
• Connection Test: Verify API functionality

🔒 Security Features

Input Validation

• API Key Formats: Strict pattern matching
• URL Validation: Proper URL structure
• Database Constraints: Safe connection parameters
• Email Formatting: Valid email address structures

Sensitive Data Handling

• Masked Display: API keys shown partially
• Secure Storage: Encrypted environment variables
• Access Logging: Configuration change tracking

🧪 Testing & Validation

⚡ Performance Settings

• Cache Configuration: Redis or file-based caching
• Queue Management: Background job processing
• Session Storage: Database or file sessions
• API Rate Limits: Throttling configuration

📊 System Monitoring

Monitor system health, performance, and usage analytics.

🏥 Health Monitoring

📈 Performance Metrics

Application Metrics

• Response Times: Average request/response latency
• Memory Usage: PHP memory consumption
• CPU Usage: Server resource utilization
• Active Sessions: Concurrent user sessions

Database Metrics

• Query Performance: Slow query identification
• Connection Pool: Database connection usage
• Storage Usage: Database size and growth
• Index Performance: Query optimization metrics

🔍 Real-time Monitoring

Health Check Endpoints

# Application health
GET /health

# Detailed system status
GET /api/system/status

# MCP Server health
GET http://localhost:3001/health

# Database connectivity
GET /api/database/status

Automated Monitoring

📊 Usage Analytics

User Activity Metrics

• Daily Active Users: Unique user sessions per day
• Feature Usage: Most used application features
• API Calls: External service usage patterns
• Conversation Volume: AI agent interaction statistics

Business Metrics

• Appointments Booked: Successful booking conversions
• Surveys Completed: Customer feedback collection rates
• Messages Sent: SMS and email communication volume
• Payment Processing: Transaction success rates

📋 Available Monitoring Commands

# Monitor application health
php artisan monitor:health

# Check usage alerts and quotas  
php artisan usage:alerts

# Validate quota system
php artisan quota:validate

# Interactive quota testing
php artisan quota:test

# Show customer details and usage
php artisan customer:show {user_id}

# Monitor specific user usage
php artisan usage:show {user_id}

🚨 Alerting & Notifications

Alert Conditions

• Service Downtime: API or database unavailability
• High Error Rates: Increased failed requests
• Performance Degradation: Response times above thresholds
• Resource Exhaustion: Memory or disk space limits

Notification Channels

• Email Alerts: Critical system notifications
• Dashboard Notifications: In-app alert system
• Log Files: Detailed error logging
• Webhook Notifications: External monitoring systems

📚 API Documentation

Comprehensive API reference for developers and system integrators.

🔗 Base URLs & Authentication

API Endpoints

# Main Application API
Base URL: https://your-domain.com/api/

# MCP Server API
Base URL: http://localhost:3001/

# Tool Integration Endpoints
Tools: https://your-domain.com/tools/

Authentication Methods

🤖 AI Agent Management API

Create AI Agent

POST /api/agents
{
  "name": "Customer Service Agent",
  "instructions": "You are a helpful customer service representative...",
  "voice_id": "voice_uuid_here",
  "is_active": true
}

List Agents

GET /api/agents
Response: {
  "data": [
    {
      "id": 1,
      "name": "Customer Service Agent",
      "voice_id": "voice_uuid",
      "is_active": true,
      "created_at": "2025-01-08T12:00:00Z"
    }
  ]
}

📅 Appointment Management API

Check Availability

GET /api/appointments/availability?date=2025-01-15&service=consultation
Response: {
  "available_slots": [
    {"time": "09:00", "duration": 60},
    {"time": "10:30", "duration": 60},
    {"time": "14:00", "duration": 60}
  ]
}

Book Appointment

POST /api/appointments
{
  "customer_name": "John Doe",
  "customer_email": "[email protected]",
  "customer_phone": "+1234567890",
  "service_type": "consultation",
  "date": "2025-01-15",
  "time": "09:00",
  "duration": 60,
  "notes": "First-time customer"
}

📊 Survey API

Create Survey

POST /api/surveys
{
  "title": "Customer Satisfaction Survey",
  "questions": [
    {
      "type": "rating",
      "text": "How would you rate our service?",
      "scale": 5
    },
    {
      "type": "text",
      "text": "What could we improve?"
    }
  ]
}

🔧 Tool Integration APIs

SMS Tool

POST /tools/sms
Headers: {
  "Content-Type": "application/json",
  "X-Webhook-Signature": "sha256=signature"
}
Body: {
  "to": "+1234567890",
  "body": "Your appointment is confirmed for tomorrow at 2 PM"
}

Email Tool

POST /tools/email
{
  "to": "[email protected]",
  "subject": "Appointment Confirmation",
  "body": "<h1>Thank you for booking!</h1><p>Your appointment details...</p>",
  "from_name": "SNIKO Support"
}

📡 Webhook Events

ElevenLabs Conversation Events

POST /webhooks/elevenlabs/conversation
{
  "event": "conversation_started",
  "conversation_id": "conv_uuid",
  "agent_id": "agent_uuid",
  "customer_phone": "+1234567890",
  "timestamp": "2025-01-08T12:00:00Z"
}

Appointment Events

POST /webhooks/appointment
{
  "event": "appointment_booked",
  "appointment_id": 123,
  "customer_email": "[email protected]",
  "scheduled_for": "2025-01-15T09:00:00Z"
}

❌ Error Handling

Common Error Codes

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid",
    "details": {
      "email": ["The email field is required"],
      "phone": ["The phone format is invalid"]
    }
  },
  "timestamp": "2025-01-08T12:00:00Z"
}

🔄 Development Workflow

Best practices and workflows for developing and maintaining SNIKO Conversational AI.

🏗️ Development Environment Setup

Local Development Stack

🚀 Development Workflow

1. Initial Setup

# Clone repository
git clone https://github.com/your-repo/snak-conversational-ai.git
cd snak-conversational-ai

# Install dependencies
composer install
npm install

# Setup environment
cp .env.example .env
php artisan key:generate

# Database setup
php artisan migrate --seed

# Install MCP server dependencies
cd mcp-servers/unified && npm install

2. Daily Development Process

1. Start Development Servers

   # Laravel development server
   php artisan serve --host=0.0.0.0 --port=8000
   
   # Frontend asset watching
   npm run dev
   
   # MCP server development
   cd mcp-servers/unified && npm run dev

2. Code Changes
   • Edit PHP files in app/ directory
   • Modify Vue.js components in resources/js/
   • Update MCP tools in mcp-servers/unified/src/
3. Testing

   # PHP tests
   php artisan test
   
   # Frontend linting
   npm run lint
   
   # Type checking
   npm run type-check

🔧 Code Standards & Guidelines

PHP/Laravel Standards

• PSR-12: PHP coding standard compliance
• Laravel Pint: Automated code formatting
• PHPStan: Static analysis for type safety
• Pest/PHPUnit: Comprehensive testing framework

JavaScript/TypeScript Standards

• ESLint: Code linting and error detection
• Prettier: Consistent code formatting
• TypeScript: Type safety for MCP server
• Vue 3: Composition API patterns

📦 Build & Deployment

Production Build Process

# Install production dependencies
composer install --no-dev --optimize-autoloader

# Build frontend assets
npm run build

# Database migrations
php artisan migrate --force

# Clear and cache configurations
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Build MCP server
cd mcp-servers/unified
npm install --production
npm run build

Deployment Checklist

🧪 Testing Strategy

Test Types

Testing Commands

# Run all tests
php artisan test

# Run specific test suite
php artisan test --testsuite=Feature

# Run tests with coverage
php artisan test --coverage

# Test specific class
php artisan test tests/Feature/AppointmentTest.php

📊 Performance Optimization

Laravel Optimization

• Opcache: PHP bytecode caching
• Queue Workers: Background job processing
• Database Indexing: Query performance optimization
• Response Caching: HTTP response optimization

Frontend Optimization

• Code Splitting: Lazy loading of Vue components
• Asset Optimization: Image and CSS minification
• CDN Integration: Static asset delivery
• Progressive Loading: Enhanced user experience

🆘 Support & Help

Get help when you need it with comprehensive support resources and troubleshooting guides.

📞 Support Channels

🔧 Self-Help Resources

System Diagnostics

# Check system health
curl http://localhost:3001/health

# Verify database connection
php artisan migrate:status

# Test external API connections
php artisan elevenlabs:test
php artisan softphone:test

# Check configuration
php artisan config:show

Log Analysis

# View Laravel logs
tail -f storage/logs/laravel.log

# Monitor MCP server logs
cd mcp-servers/unified && npm run logs

# Check system logs (Linux)
journalctl -u nginx -f
tail -f /var/log/mysql/error.log

🚨 Common Issues & Solutions

Installation Issues

API Integration Issues

📊 Performance Troubleshooting

Slow Response Times

• Enable Query Logging: Identify slow database queries
• Check Memory Usage: Monitor PHP memory consumption
• Review API Calls: Optimize external service requests
• Enable Caching: Implement Redis or file caching

High Server Load

• Queue Processing: Move heavy tasks to background jobs
• Database Optimization: Add indexes for frequent queries
• CDN Implementation: Offload static assets
• Load Balancing: Distribute traffic across servers

🛠️ Maintenance Tasks

Regular Maintenance

# Clear application caches
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

# Update dependencies
composer update
npm update

# Database maintenance
php artisan migrate
php artisan queue:restart

# Log rotation
php artisan log:clear

Security Updates

• Dependency Updates: Regular security patches
• SSL Certificate Renewal: Maintain HTTPS encryption
• API Key Rotation: Periodic credential updates
• Access Review: Regular user permission audits

📋 Support Request Information

🎓 Learning Resources

• Video Tutorials: Step-by-step setup and configuration
• Best Practices Guide: Optimization and security recommendations
• API Examples: Code samples for integration
• Community Forum: User discussions and shared solutions
• Webinar Series: Live training sessions

💳 Billing & Subscriptions

Understanding your SNIKO subscription and how billing works.

Understanding Your Plan

Payment Methods

Billing Features

• Automatic Renewal: Your subscription renews automatically
• Usage Tracking: See exactly what you're using
• Invoice History: Download past invoices
• Payment History: Track all payments
• Plan Changes: Upgrade or downgrade anytime
• Prorated Billing: Only pay for what you use

Managing Your Subscription

You can manage your subscription from your dashboard:

1. Go to "Billing" in your dashboard
2. View your current plan and usage
3. Change your payment method
4. Upgrade or downgrade your plan
5. Download invoices and receipts
6. Cancel your subscription if needed

💳 Stripe Recurring Pricing

SNIKO uses Stripe for secure, reliable recurring billing. Here's everything you need to know about how pricing works.

How Stripe Billing Works

Available Pricing Plans

How Billing Works

• Automatic Renewal: Your subscription renews automatically
• Usage Tracking: SNIKO tracks your usage in real-time
• Overage Charges: Pay only for what you use beyond your plan
• Annual Discounts: Save up to 20% with annual billing
• Prorated Billing: Only pay for the time you use
• No Setup Fees: Start using SNIKO immediately

Accepted Payment Methods

Billing Security & Privacy

• PCI Compliant: Meets highest security standards
• Encrypted Data: All payment information is encrypted
• No Storage: We never store your payment details
• Fraud Protection: Advanced fraud detection
• Secure Processing: Bank-level security

🛠️ Troubleshooting Guide

Comprehensive troubleshooting guide for resolving common issues with SNIKO Conversational AI.

🚨 Critical Issues

Application Won't Start

# Check PHP version and extensions
php -v
php -m | grep -E 'curl|json|openssl|mbstring'

# Verify file permissions
chmod -R 755 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

# Clear caches and regenerate keys
php artisan key:generate
php artisan config:clear
php artisan cache:clear

Database Connection Issues

# Test database connection
php artisan migrate:status

# Check database credentials in .env
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=snak_ai
DB_USERNAME=your_username
DB_PASSWORD=your_password

# Verify database server is running
mysql -h 127.0.0.1 -u your_username -p

🎤 ElevenLabs Integration Issues

API Connection Problems

Diagnostic Commands

# Set up ElevenLabs API integration
php artisan setup:elevenlabs

# Check configuration values
php artisan config:cache
php artisan tinker --execute="dump(config('elevenlabs.api_key'))"

# Sync voices from ElevenLabs API
php artisan sync:elevenlabs-voices

# Test API connectivity manually
curl -H "xi-api-key: your_key" https://api.elevenlabs.io/v1/user

📞 Twilio Softphone Issues

Call Setup Problems

Softphone Diagnostics

# Check Twilio setup status and show webhook URLs
php artisan softphone:setup --show-urls

# Quick setup for development (interactive)
php artisan softphone:quick-setup

# Complete automated setup
php artisan softphone:complete-setup

# Update webhook URLs
php artisan softphone:update-webhooks

# Verify webhook URLs respond
curl -I https://your-domain.com/softphone/voice

🔗 MCP Server Issues

Server Won't Start

# Check Node.js version
node --version  # Should be 18+

# Install dependencies
cd mcp-servers/unified
npm install

# Check for port conflicts
netstat -an | grep :3001
lsof -i :3001

# Start in debug mode
npm run dev

Tool Integration Problems

💳 Payment & Billing Issues

Stripe Integration Problems

# Test Stripe connection
curl -u sk_test_your_key: https://api.stripe.com/v1/account

# Verify webhook endpoint
curl -X POST https://your-domain.com/stripe/webhook \
  -H "Content-Type: application/json" \
  -d '{"test": "webhook"}'

# Check environment setting
PAYMENT_ENVIRONMENT=sandbox  # or 'live'

Common Payment Errors

• Invalid API Key: Check key format and environment match
• Webhook Verification Failed: Verify webhook secret configuration
• Currency Mismatch: Ensure consistent currency settings
• SSL Required: All payment endpoints must use HTTPS

📧 Email & SMS Issues

SMTP Configuration Problems

# Test SMTP connection manually
php artisan tinker
Mail::raw('Test email', function ($message) {
    $message->to('[email protected]')->subject('Test');
});

# Common SMTP settings
Gmail: smtp.gmail.com:587 (TLS)
Outlook: smtp.office365.com:587 (TLS)
SendGrid: smtp.sendgrid.net:587 (TLS)

SMS Delivery Issues

• Invalid Phone Format: Use E.164 format (+1234567890)
• Messaging Service Errors: Check Twilio Messaging Service SID
• Rate Limits: Monitor SMS sending quotas
• Geographic Restrictions: Verify country/region support

🔍 Performance Issues

Slow Response Times

# Enable query logging
DB_LOG_QUERIES=true

# Check slow queries
php artisan db:monitor

# Monitor memory usage
php artisan horizon:status
php artisan queue:monitor

# Cache optimization
php artisan config:cache
php artisan route:cache
php artisan view:cache

High Resource Usage

• Memory Leaks: Monitor PHP memory usage and restart workers
• Database Performance: Add indexes and optimize queries
• API Rate Limits: Implement caching and request batching
• File Storage: Clean up logs and temporary files regularly

🛡️ Security & Access Issues

Authentication Problems

SSL Certificate Issues

# Check SSL certificate
curl -vI https://your-domain.com

# Verify certificate validity
openssl s_client -connect your-domain.com:443 -servername your-domain.com

# Test webhook SSL
curl -X POST https://your-domain.com/webhooks/test \
  --cert-status -v

Environment File Security Issues

Secure Environment Setup

# Replace all production keys in .env.example with placeholders:
ELEVENLABS_API_KEY=your_elevenlabs_api_key_here
STRIPE_KEY=your_stripe_publishable_key_here  
STRIPE_SECRET=your_stripe_secret_key_here
TWILIO_ACCOUNT_SID=your_twilio_account_sid_here
TWILIO_AUTH_TOKEN=your_twilio_auth_token_here

# Verify no live keys in examples
grep -r "sk_" .env.example
grep -r "pk_live" .env.example

API Key Security Best Practices

• Environment Separation: Use different keys for dev/staging/prod
• Key Rotation: Change API keys regularly (monthly/quarterly)
• Permission Restrictions: Limit API key scopes and permissions
• Version Control Safety: Never commit live keys to repositories
• Access Monitoring: Monitor API key usage and unusual activity

🚀 Quick Recovery Steps

Emergency System Reset

# 1. Clear all caches
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

# 2. Restart services
sudo systemctl restart nginx
sudo systemctl restart php8.2-fpm
sudo systemctl restart mysql

# 3. Restart background jobs
php artisan queue:restart
php artisan schedule:run

# 4. Check system health
php artisan health:check
curl http://localhost:3001/health

📞 Getting Help

Log Collection for Support

# Collect system logs
tail -n 100 storage/logs/laravel.log > debug.log
tail -n 100 /var/log/nginx/error.log >> debug.log
journalctl -u php8.2-fpm -n 50 >> debug.log

# System information
php artisan about > system-info.txt
curl http://localhost:3001/health >> system-info.txt

Before Contacting Support

• ✅ Try the quick recovery steps above
• ✅ Collect relevant error logs
• ✅ Document steps to reproduce the issue
• ✅ Note any recent changes or updates
• ✅ Include system information and configuration

💡 Tips & Best Practices

Get the most out of SNIKO with these expert tips!

🤖 Agent Best Practices

🎭 Voice Selection Tips

• Match Your Brand: Choose voices that fit your business personality
• Consider Your Audience: What voice would your customers prefer?
• Test Multiple Options: Try different voices to find the best fit
• Stay Consistent: Use the same voice across all interactions
• Consider Accent: Choose voices that match your target market

📞 Conversation Tips

📅 Appointment Management

• Set Clear Availability: Be specific about when you're available
• Add Buffer Time: Leave time between appointments
• Send Reminders: Automatically remind customers
• Handle Changes: Make rescheduling easy
• Follow Up: Check in after appointments

📊 Survey Best Practices

• Keep It Short: Don't overwhelm customers
• Ask Relevant Questions: Only ask what you need to know
• Use Simple Language: Make questions easy to understand
• Offer Incentives: Consider rewards for completing surveys
• Act on Feedback: Use responses to improve your business

🚀 Growing Your Business

💡 Pro Tips