Skip to main content

API Reference Overview

Complete reference for InHotel Focus Chat components, configuration parameters, and programmatic usage.

Core Components​

<focus-chat> Element​

The main custom element that provides chat functionality.

Attributes:

  • agent_card_url (required): URL to agent card JSON
  • config (optional): JSON configuration string or script selector

Example:

<focus-chat 
  agent_card_url="https://agent.example.com/card.json"
  config='{"greeting": "Hello!"}'
>
</focus-chat>

Learn more about the focus-chat element →

Configuration System​

Parameter Categories​

  • UI Styling: Colors, fonts, layout
  • Behavior: Streaming, context, triggers
  • Messages: Greetings, placeholders

Configuration Methods​

  1. Inline JSON: Direct JSON string in config attribute
  2. Script Reference: Reference to <script type="application/json"> element
  3. CSS Variables: Dynamic theming with custom properties

Complete configuration reference →

Agent Card Format​

Required Fields​

{
  "name": "Agent Name",
  "description": "Agent description", 
  "url": "https://api.example.com/chat"
}

Optional Extensions​

{
  "capabilities": {
    "streaming": true,
    "extensions": [
      {
        "uri": "inhotel-metadata",
        "params": {
          "displayName": "Full Name",
          "role": "Role",
          "organization": "Company"
        }
      }
    ]
  }
}

Chat Protocol​

Request Format​

{
  "message": "User message",
  "context": "Page context (if configured)",
  "history": [
    {"role": "user", "content": "Previous message"},
    {"role": "assistant", "content": "Previous response"}
  ]
}

Response Formats​

Regular Response​

{
  "content": "Assistant response message"
}

Streaming Response (Server-Sent Events)​

data: {"content": "Hello"}
data: {"content": " there!"}
data: [DONE]

Browser APIs Used​

Web Standards​

  • Custom Elements: For <focus-chat> registration
  • Shadow DOM: For style encapsulation
  • Fetch API: For HTTP requests
  • EventSource: For streaming responses
  • Web Storage: For conversation history

Compatibility​

  • Chrome 54+
  • Firefox 63+
  • Safari 10.1+
  • Edge 79+

Event System​

Initialization Events​

// Widget initialized
console.log('[InHotel] Widget initialized');

// Agent card loaded
console.log('[InHotel] Agent card loaded');

Interaction Events​

// Message sent
console.log('[InHotel] Message sent');

// Response received
console.log('[InHotel] Response received');

Streaming Events​

// Streaming connection established
console.log('[InHotel Streaming] Connection established');

// Stream chunk received
console.log('[InHotel Streaming] Event received');

Storage Management​

Session Storage​

  • Key Format: inhotel_history_{agentId}_{sectionKey}
  • Purpose: Conversation history per agent/context
  • Lifetime: Browser session

Local Storage​

  • Key: inhotel_global_history
  • Purpose: Cross-session history tracking
  • Lifetime: Until manually cleared

Error Handling​

Common Error Scenarios​

  1. Agent Card Loading Failed

    • Invalid URL
    • CORS issues
    • JSON parsing errors

  2. Chat Endpoint Errors

    • Network failures
    • Invalid responses
    • Timeout issues

  3. Configuration Errors

    • Invalid JSON syntax
    • Missing required parameters
    • Type mismatches

Error Recovery​

  • Graceful degradation for non-critical features
  • Automatic fallback from streaming to regular requests
  • Default values for missing configuration parameters

Performance Considerations​

Loading Optimization​

  • Script loading is asynchronous
  • Agent cards are cached in memory
  • Minimal DOM manipulation

Memory Management​

  • Automatic cleanup of event listeners
  • Conversation history limits
  • Efficient Shadow DOM usage

Network Optimization​

  • HTTP/2 compatible
  • Streaming reduces perceived latency
  • Efficient JSON serialization

Security Features​

Content Security Policy​

Focus Chat is compatible with strict CSP policies:

<meta http-equiv="Content-Security-Policy" content="
  default-src 'self';
  script-src 'self' https://embed.agents.inhotel.io;
  connect-src 'self' https://agent.example.com;
  style-src 'self' 'unsafe-inline';
">

Data Handling​

  • No sensitive data stored in localStorage
  • HTTPS required for production
  • Agent endpoints should validate inputs

CORS Requirements​

Agent card and chat endpoints must include:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: Content-Type

Integration Patterns​

Single Page Applications​

// React example
useEffect(() => {
  const script = document.createElement('script');
  script.src = 'https://embed.agents.inhotel.io/focus-chat/latest/focus-chat.min.js';
  document.head.appendChild(script);
  
  return () => document.head.removeChild(script);
}, []);

Server-Side Rendering​

<!-- Include in HTML template -->
<script src="https://embed.agents.inhotel.io/focus-chat/latest/focus-chat.min.js" defer></script>
<focus-chat agent_card_url="{{agent_url}}" config="{{config_json}}"></focus-chat>

Content Management Systems​

// WordPress shortcode example
function focus_chat_shortcode($atts) {
    return sprintf(
        '<focus-chat agent_card_url="%s" config=\'%s\'></focus-chat>',
        esc_url($atts['agent_card_url']),
        esc_attr($atts['config'])
    );
}

Debugging and Development​

Debug Mode​

Enable verbose logging by checking browser console for [InHotel] prefixed messages.

Development Tools​

// Access widget instance
const widget = document.querySelector('focus-chat');

// Check configuration
console.log(widget.getAttribute('config'));

// Verify agent card loading
console.log('[InHotel] Agent card:', widget._agentCard);

Testing Checklist​

  • Agent card URL accessible
  • CORS headers configured
  • Chat endpoint responding
  • Configuration JSON valid
  • Browser console error-free

Migration Guide​

From v0.1.0 to v0.2.0​

  • No breaking changes
  • New styling parameters available
  • Enhanced performance

Deprecation Notices​

  • Alternative parameter names maintained for backward compatibility
  • No deprecated features in current version

Next Steps​