NEAVO Real-Time Intent API Documentation

wss://api.neavo.io/v1/realtime?token=YOUR_API_KEY

// Initialize WebSocket connection
const ws = new WebSocket('wss://api.neavo.io/v1/realtime?token=YOUR_API_KEY');

ws.onopen = function(event) {
    console.log('Connected to NEAVO Real-Time API');
    
    // Configure your settings
    ws.send(JSON.stringify({
        type: 'configure',
        settings: {
            drop_alert_threshold: 75,    // Alert when drop risk >= 75%
            update_frequency: 2,         // Updates every 2 seconds
            page_transition_reset: true, // Reset scores on page change
            minimum_session_time: 5      // Start sending data after 5 seconds
        }
    }));
};

ws.onmessage = function(event) {
    const message = JSON.parse(event.data);
    handleRealtimeData(message);
};

ws.onerror = function(error) {
    console.error('WebSocket error:', error);
};

ws.onclose = function(event) {
    console.log('Connection closed:', event.code, event.reason);
    handleReconnection();
};

{
    "type": "engagement_update",
    "timestamp": "2025-08-17T10:30:15Z",
    "session_id": "sess_abc123",
    "page_url": "https://example.com/landing-page",
    "data": {
        "attention_score": 72,      // 0-100: Current attention level
        "engagement_score": 68,     // 0-100: Overall engagement
        "trend": "increasing",      // "increasing", "stable", "decreasing"
        "confidence": 0.85,         // 0-1: Model confidence
        "session_duration": 45.2    // Seconds since session start
    }
}

{
    "type": "segment_interest",
    "timestamp": "2025-08-17T10:30:18Z",
    "session_id": "sess_abc123",
    "page_url": "https://example.com/product-page",
    "data": {
        "segment_id": "pricing_section",
        "interest_score": 89,           // 0-100: Interest in this segment
        "relative_interest": "high",    // "low", "medium", "high"
        "time_engaged": 15.2,          // Seconds spent on segment
        "interaction_depth": "deep",    // "surface", "moderate", "deep"
        "segment_type": "feature"       // "feature", "pricing", "demo", "content"
    }
}

{
    "type": "drop_alert",
    "timestamp": "2025-08-17T10:30:20Z",
    "session_id": "sess_abc123",
    "page_url": "https://example.com/checkout",
    "data": {
        "risk_level": "high",                           // "low", "medium", "high", "critical"
        "drop_probability": 82,                         // 0-100: Likelihood of abandonment
        "estimated_time_to_drop": 8.5,                 // Seconds until predicted drop
        "trigger_factors": ["rapid_scroll", "decreased_attention"],
        "recommended_action": "immediate_engagement",   // Suggested intervention
        "page_section": "payment_form"                  // Where the risk was detected
    }
}

ws.onmessage = function(event) {
    const message = JSON.parse(event.data);
    
    if (message.type === 'engagement_update') {
        const { attention_score, engagement_score, trend } = message.data;
        
        // Low engagement detected - switch creative
        if (attention_score < 40 && trend === 'decreasing') {
            switchCreative('high_performance', message.session_id);
            logEvent('creative_switch_low_engagement', message);
        }
        
        // High engagement - maintain current creative
        if (engagement_score > 80 && trend === 'increasing') {
            analyzeSuccessfulCreative(message.session_id);
            logEvent('creative_success', message);
        }
    }
};

function switchCreative(performanceLevel, sessionId) {
    // Integration with ad platforms
    updateAdCreative({
        platforms: ['google_ads', 'facebook_ads'],
        new_creative_id: `creative_${performanceLevel}_v2`,
        reason: 'low_engagement_detected',
        session_data: sessionId
    });
}

const bidAdjustmentRules = {
    high_intent: { modifier: 1.4, reason: 'high_engagement_detected' },
    medium_intent: { modifier: 1.1, reason: 'medium_engagement_detected' },
    low_intent: { modifier: 0.8, reason: 'low_engagement_detected' },
    drop_risk: { modifier: 0.6, reason: 'high_drop_probability' }
};

ws.onmessage = function(event) {
    const message = JSON.parse(event.data);
    
    if (message.type === 'segment_interest') {
        const { interest_score, relative_interest } = message.data;
        
        // High-intent traffic detected - increase bids
        if (relative_interest === 'high' && interest_score > 85) {
            adjustCampaignBids({
                campaign_ids: ['camp_123', 'camp_124'],
                adjustment: bidAdjustmentRules.high_intent,
                trigger_data: message.data,
                duration_minutes: 15
            });
        }
    }
};

const audienceSegments = {
    high_intent_pricing: [],
    feature_interested: [],
    demo_engaged: [],
    about_to_convert: []
};

const userProfiles = new Map();

ws.onmessage = function(event) {
    const message = JSON.parse(event.data);
    const { session_id } = message;
    
    // Initialize user profile
    if (!userProfiles.has(session_id)) {
        userProfiles.set(session_id, {
            interests: {},
            engagement_history: [],
            predicted_intent: 'unknown'
        });
    }
    
    if (message.type === 'segment_interest') {
        const { segment_id, interest_score, segment_type } = message.data;
        const userProfile = userProfiles.get(session_id);
        
        // Update user interest profile
        userProfile.interests[segment_id] = {
            score: interest_score,
            type: segment_type,
            timestamp: Date.now()
        };
        
        // Categorize user based on segment interest
        if (segment_type === 'pricing' && interest_score > 80) {
            addToAudience(session_id, 'high_intent_pricing', {
                interest_score,
                segment_id
            });
        }
        
        if (segment_type === 'demo' && interest_score > 75) {
            addToAudience(session_id, 'demo_engaged', {
                interest_score,
                demo_completion: calculateDemoCompletion(userProfile)
            });
        }
    }
    
    if (message.type === 'engagement_update') {
        const { engagement_score, trend } = message.data;
        
        // High engagement - likely to convert
        if (engagement_score > 85 && trend === 'increasing') {
            addToAudience(session_id, 'about_to_convert', {
                engagement_score,
                conversion_probability: calculateConversionProbability()
            });
        }
    }
};

function addToAudience(sessionId, audienceType, metadata) {
    audienceSegments[audienceType].push({
        session_id: sessionId,
        added_at: Date.now(),
        metadata: metadata,
        expires_at: Date.now() + (30 * 24 * 60 * 60 * 1000) // 30 days
    });
    
    // Sync with advertising platforms
    syncWithAdPlatforms(sessionId, audienceType, metadata);
}

function syncWithAdPlatforms(sessionId, audienceType, metadata) {
    // Facebook Custom Audiences
    addToFacebookAudience({
        audience_name: `neavo_${audienceType}`,
        user_identifier: sessionId,
        metadata: metadata
    });
    
    // Google Customer Match
    addToGoogleAudience({
        audience_id: `goog_${audienceType}`,
        user_data: { session_id: sessionId, interest_data: metadata }
    });
}

const configurationOptions = {
    type: 'configure',
    settings: {
        // Drop Alert Configuration
        drop_alert_threshold: 75,        // Minimum risk % to trigger alert
        
        // Update Frequency
        update_frequency: 2,             // Seconds between updates (1-10)
        minimum_session_time: 5,         // Start sending data after X seconds
        
        // Session Management
        page_transition_reset: true,     // Reset scores on page change
        session_timeout: 1800,           // Session timeout in seconds (30 min)
        
        // Advanced Options
        confidence_threshold: 0.7,       // Minimum model confidence
        include_metadata: true           // Include additional context data
    }
};

// Send configuration
ws.send(JSON.stringify(configurationOptions));

class NEAVOWebSocket {
    constructor(apiKey) {
        this.apiKey = apiKey;
        this.reconnectAttempts = 0;
        this.maxReconnectAttempts = 5;
        this.reconnectDelay = 1000;
        this.isConnected = false;
        this.messageQueue = [];
    }
    
    connect() {
        try {
            this.ws = new WebSocket(`wss://api.neavo.io/v1/realtime?token=${this.apiKey}`);
            this.setupEventHandlers();
        } catch (error) {
            console.error('Failed to create WebSocket connection:', error);
            this.handleConnectionError(error);
        }
    }
    
    handleConnectionClose(event) {
        const { code, reason } = event;
        
        switch (code) {
            case 1000: // Normal closure
                console.log('Connection closed normally');
                break;
            case 4000: // Invalid API key
                console.error('Invalid API key');
                break;
            case 4001: // Rate limit exceeded
                console.error('Rate limit exceeded');
                setTimeout(() => this.attemptReconnect(), 60000);
                break;
            default:
                this.attemptReconnect();
        }
    }
    
    attemptReconnect() {
        if (this.reconnectAttempts >= this.maxReconnectAttempts) {
            console.error('Max reconnection attempts reached');
            return;
        }
        
        const delay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts);
        setTimeout(() => {
            this.reconnectAttempts++;
            this.connect();
        }, delay);
    }
}

// GTM Custom HTML Tag
window.dataLayer = window.dataLayer || [];

// Initialize NEAVO client
const neavo = new NEAVOWebSocket('{{NEAVO_API_KEY}}');

neavo.onMessage = (message) => {
    // Push NEAVO data to GTM dataLayer
    window.dataLayer.push({
        'event': 'neavo_' + message.type,
        'neavo_session_id': message.session_id,
        'neavo_data': message.data
    });
    
    // Trigger specific GTM events
    if (message.type === 'drop_alert' && message.data.risk_level === 'high') {
        window.dataLayer.push({
            'event': 'neavo_high_drop_risk',
            'drop_probability': message.data.drop_probability
        });
    }
};

neavo.connect();

// Send NEAVO events to Zapier
function sendToZapier(message) {
    const webhookUrl = 'https://hooks.zapier.com/hooks/catch/YOUR_WEBHOOK_ID/';
    
    fetch(webhookUrl, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            event_type: message.type,
            timestamp: message.timestamp,
            session_id: message.session_id,
            data: message.data
        })
    });
}

neavo.onMessage = (message) => {
    if (message.type === 'drop_alert' || 
        (message.type === 'segment_interest' && message.data.interest_score > 80)) {
        sendToZapier(message);
    }
};