AI Communication API Endpoints

This page provides the complete API reference for the AI Communication API.

OpenAPI Specification

The complete OpenAPI specification for the AI Communication API is available at openapi.yaml.

AI Response Generation Workflows

Generate Response Suggestions

// Generate AI response suggestion for guest inquiry
const responseSuggestion = await fetch('/api/v1/ai/conversations/suggest-response', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${staffToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    conversation_id: 'conv_abc123',
    guest_message: 'I need extra towels and the air conditioning in my room is too cold',
    guest_context: {
      guest_id: 'guest_456',
      guest_name: 'Sarah Johnson',
      room_number: '205',
      stay_duration: 3,
      guest_tier: 'gold_member',
      previous_requests: ['housekeeping', 'room_service'],
      preferences: {
        room_temperature: 'warm',
        communication_style: 'formal'
      }
    },
    conversation_history: [
      {
        sender: 'guest',
        message: 'Thank you for the welcome amenities',
        timestamp: '2024-01-15T10:00:00Z',
        sentiment: 'positive'
      }
    ]
  })
});

const {
  suggested_response,
  confidence_score,
  intent_classification,
  sentiment_analysis,
  recommended_actions,
  escalation_suggested
} = await responseSuggestion.json();

Automated Response with Intelligence

// Send automated response with AI confidence checking
const autoResponse = await fetch('/api/v1/ai/conversations/auto-respond', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${staffToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    conversation_id: 'conv_abc123',
    guest_message: 'What time does the spa close today?',
    response_settings: {
      auto_send_threshold: 0.8,
      fallback_to_human: true,
      include_recommendations: true,
      personalization_level: 'high'
    },
    business_context: {
      current_time: '2024-01-15T14:30:00Z',
      special_events: ['couples_massage_special'],
      availability_status: 'available'
    }
  })
});

const {
  response_sent,
  message_id,
  confidence_score,
  routed_to_human,
  ai_model_used,
  response_time_ms,
  additional_recommendations
} = await autoResponse.json();

Advanced Sentiment Analysis

Comprehensive Sentiment Analysis

// Analyze conversation sentiment with context
const sentimentAnalysis = await fetch('/api/v1/ai/conversations/analyze-sentiment', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${staffToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    conversation_id: 'conv_abc123',
    messages: [
      {
        sender: 'guest',
        content: 'The room is beautiful but I\'m disappointed with the slow WiFi',
        timestamp: '2024-01-15T10:30:00Z'
      },
      {
        sender: 'staff',
        content: 'I apologize for the WiFi issues. Let me connect you with our IT team',
        timestamp: '2024-01-15T10:35:00Z'
      }
    ],
    analysis_scope: 'full_conversation',
    include_predictions: true
  })
});

const {
  overall_sentiment,
  sentiment_score,
  emotion_analysis,
  intent_classification,
  urgency_level,
  satisfaction_prediction,
  key_issues_identified,
  recommended_actions,
  escalation_triggers,
  guest_satisfaction_trend
} = await sentimentAnalysis.json();

Real-time Sentiment Monitoring

// Monitor sentiment changes in real-time
const sentimentMonitoring = await fetch('/api/v1/ai/conversations/monitor-sentiment', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${staffToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    guest_id: 'guest_456',
    monitoring_period: '24_hours',
    alert_thresholds: {
      negative_sentiment: -0.6,
      urgency_escalation: 'high',
      satisfaction_drop: 0.3
    },
    notification_preferences: {
      immediate_alerts: true,
      summary_reports: 'hourly',
      dashboard_updates: 'real_time'
    }
  })
});

Intelligent Service Recommendations

Generate Personalized Recommendations

// Create personalized service recommendations
const recommendations = await fetch('/api/v1/ai/recommendations/generate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${staffToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    guest_id: 'guest_456',
    recommendation_context: {
      stay_type: 'business',
      duration: 4,
      group_size: 1,
      special_occasions: ['birthday'],
      weather_context: 'rainy_day',
      time_of_stay: 'evening'
    },
    guest_profile: {
      preferences: ['spa_services', 'fine_dining', 'quiet_activities'],
      dietary_restrictions: ['vegetarian'],
      previous_bookings: ['spa_massage', 'room_service'],
      spending_pattern: 'premium',
      communication_style: 'detailed'
    },
    business_factors: {
      inventory_levels: 'normal',
      promotional_campaigns: ['spa_weekend_special'],
      revenue_targets: 'monthly_upsell_focus',
      staff_availability: 'high'
    }
  })
});

const {
  recommendations,
  personalization_score,
  confidence_levels,
  expected_revenue,
  optimal_timing,
  presentation_strategy
} = await recommendations.json();

Contextual Upselling Recommendations

// Generate contextual upselling opportunities
const upsellRecommendations = await fetch('/api/v1/ai/recommendations/upselling', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${staffToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    guest_id: 'guest_456',
    current_conversation_context: {
      last_message: 'The dinner at your restaurant was excellent',
      sentiment: 'very_positive',
      intent: 'compliment',
      conversation_stage: 'engaged'
    },
    upsell_categories: ['dining', 'spa', 'room_upgrade'],
    timing_strategy: 'immediate_opportunity',
    personalization_level: 'high'
  })
});

Automated Workflow Management

Trigger Intelligent Workflows

// Initiate AI-powered workflow sequence
const workflowTrigger = await fetch('/api/v1/ai/workflows/trigger', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${staffToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    workflow_type: 'comprehensive_welcome_sequence',
    guest_id: 'guest_456',
    trigger_context: {
      arrival_time: '2024-01-15T15:00:00Z',
      room_number: '205',
      stay_duration: 3,
      special_requests: ['late_checkout', 'restaurant_reservation'],
      guest_tier: 'platinum'
    },
    personalization_settings: {
      communication_style: 'warm_professional',
      information_depth: 'comprehensive',
      recommendation_frequency: 'moderate',
      follow_up_cadence: 'twice_daily'
    },
    business_objectives: {
      upselling_focus: ['spa_services', 'dining_experiences'],
      satisfaction_priority: 'high',
      revenue_target: 'above_average'
    }
  })
});

const {
  workflow_id,
  execution_status,
  scheduled_actions,
  next_interaction_time,
  estimated_completion,
  success_metrics
} = await workflowTrigger.json();

Dynamic Workflow Adjustment

// Modify running workflow based on real-time feedback
const workflowAdjustment = await fetch(`/api/v1/ai/workflows/${workflowId}/adjust`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${staffToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    adjustment_trigger: 'negative_sentiment_detected',
    new_parameters: {
      escalation_level: 'immediate_human_handoff',
      communication_tone: 'apologetic_solution_focused',
      priority_level: 'urgent',
      specialized_staff_required: 'guest_relations_manager'
    },
    context_update: {
      guest_complaint: 'Room not ready at check-in time',
      current_sentiment: -0.7,
      urgency_assessment: 'high'
    }
  })
});

Intent Recognition and Classification

Advanced Intent Analysis

// Comprehensive intent analysis with entity extraction
const intentAnalysis = await fetch('/api/v1/ai/conversations/analyze-intent', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${staffToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    text: 'I need to change my spa appointment from tomorrow morning to tomorrow afternoon, and also book a table for two at your Italian restaurant for tonight',
    conversation_context: {
      guest_id: 'guest_456',
      current_bookings: ['spa_massage_2024-01-16_10:00'],
      conversation_history: ['spa_booking_inquiry', 'dining_questions'],
      guest_preferences: ['flexible_scheduling', 'italian_cuisine']
    },
    analysis_depth: 'comprehensive',
    entity_extraction: true,
    action_planning: true
  })
});

const {
  primary_intent,
  secondary_intents,
  confidence_scores,
  extracted_entities,
  action_plan,
  complexity_assessment,
  routing_recommendation,
  estimated_resolution_time
} = await intentAnalysis.json();

AI Model Configuration and Optimization

Configure AI Models

// Configure AI model settings for optimal performance
const modelConfig = await fetch('/api/v1/ai/models/configure', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${adminToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    primary_model: 'gpt-4-turbo',
    fallback_models: ['claude-3-sonnet', 'gemini-pro'],
    model_selection_strategy: 'dynamic_based_on_context',
    performance_settings: {
      response_temperature: 0.7,
      max_tokens: 200,
      top_p: 0.9,
      frequency_penalty: 0.1
    },
    response_customization: {
      tone: 'professional_friendly',
      formality_level: 'adaptive',
      length_preference: 'concise_detailed',
      cultural_sensitivity: 'high'
    },
    quality_controls: {
      confidence_threshold: 0.75,
      inappropriate_content_filter: 'strict',
      factual_accuracy_check: true,
      brand_voice_consistency: true
    }
  })
});

Model Performance Monitoring

// Monitor AI model performance metrics
const modelPerformance = await fetch('/api/v1/ai/models/performance', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${staffToken}`
  },
  params: new URLSearchParams({
    time_period: 'last_7_days',
    metrics: 'accuracy,confidence,response_time,satisfaction',
    breakdown_by: 'model,intent_type,guest_tier'
  })
});

const {
  overall_metrics,
  model_comparison,
  performance_trends,
  optimization_recommendations,
  cost_analysis,
  quality_scores
} = await modelPerformance.json();

Conversation Routing Intelligence

Smart Routing Decisions

// Make intelligent routing decisions based on comprehensive analysis
const routingDecision = await fetch('/api/v1/ai/conversations/routing-analysis', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${staffToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    conversation_id: 'conv_abc123',
    current_message: 'This is completely unacceptable! I\'ve been waiting for 2 hours and nobody has fixed the problem with my room key',
    guest_context: {
      guest_tier: 'platinum',
      current_sentiment: 'very_negative',
      interaction_history: ['previous_complaints', 'service_recovery_needed'],
      stay_value: 'high_revenue'
    },
    operational_context: {
      staff_availability: {
        guest_relations: 'available',
        front_desk: 'busy',
        manager_on_duty: 'available'
      },
      current_workload: 'moderate',
      escalation_queue_length: 3
    },
    routing_preferences: {
      vip_prioritization: true,
      negative_sentiment_escalation: 'immediate',
      specialist_routing: 'when_available'
    }
  })
});

const {
  routing_recommendation,
  confidence_level,
  recommended_staff_member,
  urgency_classification,
  expected_resolution_path,
  escalation_timeline,
  success_probability
} = await routingDecision.json();

Performance Analytics and Insights

Comprehensive AI Analytics

// Get detailed AI performance analytics
const aiAnalytics = await fetch('/api/v1/ai/analytics/comprehensive', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${managerToken}`
  },
  params: new URLSearchParams({
    analysis_period: 'last_30_days',
    metrics: 'response_accuracy,guest_satisfaction,revenue_impact,efficiency_gains',
    segmentation: 'guest_tier,intent_type,time_of_day,staff_involvement'
  })
});

const {
  performance_summary,
  guest_satisfaction_metrics,
  operational_efficiency,
  revenue_impact_analysis,
  ai_human_collaboration_stats,
  improvement_opportunities,
  benchmark_comparisons,
  predictive_insights
} = await aiAnalytics.json();

Real-time Performance Dashboard Data

// Get real-time dashboard metrics for AI operations
const dashboardMetrics = await fetch('/api/v1/ai/analytics/dashboard', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${staffToken}`
  }
});

const {
  active_conversations,
  ai_response_rate,
  human_escalation_rate,
  average_confidence_score,
  guest_satisfaction_trend,
  response_time_metrics,
  cost_efficiency_indicators,
  quality_score_distribution
} = await dashboardMetrics.json();

Error Handling and Best Practices

Error Response Examples

{
  "error": {
    "code": "AI_MODEL_CONFIDENCE_LOW",
    "message": "AI confidence below threshold, routing to human agent",
    "details": {
      "confidence_score": 0.45,
      "confidence_threshold": 0.75,
      "routing_decision": "human_agent_required",
      "recommended_staff_type": "guest_relations_specialist",
      "escalation_reason": "complex_multi_intent_query"
    },
    "recovery_actions": [
      "Route conversation to available human agent",
      "Provide AI-suggested talking points to staff",
      "Monitor conversation for quality assurance"
    ]
  }
}

Common Error Codes

• AI_MODEL_UNAVAILABLE (503) - Primary AI service temporarily unavailable
• INSUFFICIENT_CONTEXT (400) - Inadequate context for accurate AI response
• CONFIDENCE_BELOW_THRESHOLD (422) - AI confidence too low for autonomous response
• RATE_LIMIT_EXCEEDED (429) - Too many AI requests within time window
• INAPPROPRIATE_CONTENT_DETECTED (400) - Content violates communication policies
• GUEST_SENTIMENT_CRITICAL (202) - Negative sentiment requires human intervention
• COMPLEX_INTENT_DETECTED (422) - Multi-faceted query beyond AI capabilities
• PERSONALIZATION_DATA_MISSING (400) - Insufficient guest data for personalized response