WebSocket Message Types

The ProductFlo WebSocket API uses a structured message format with different message codes for various operations. This page details all available message types and their data structures.

Base Message Structure

All WebSocket messages share a common base structure:

{
  "code": "message_code",        // Required: Determines message handling
  "user_id": "user-123",         // Required: Sender user ID
  "room_id": "room-456",         // Optional: Target room for broadcasting  
  "timestamp": "2024-05-19T10:30:45Z", // Optional: Auto-added if omitted
  "data": {                      // Required: Message-specific payload
    // Varies by message type
  }
}

Response Structure

All server responses follow this structure:

{
  "status": "success",           // "success", "error", or "pending"
  "code": "response_code",       // Response type
  "user_id": "user-123",         // User ID
  "room_id": "room-456",         // Room ID (if applicable)
  "timestamp": "2024-05-19T10:30:45Z",
  "data": {                      // Response data
    // Varies by response type
  }
}

Message Codes (CodeType Enum)

The WebSocket API uses the CodeType enum to define message types:

Client-to-Server Message Codes

string

Standard chat messages

string

Messages for the Haitch AI assistant

string

Product idea generation requests

string

Documentation generation requests

string

Engineering-specific requests (CAD, DFM, etc.)

Server-to-Client Message Codes

string

Response to standard chat messages

string

Response to idea generation requests

string

Response to documentation generation requests

string

Response to engineering-specific requests

System Message Codes

string

System messages (connection status, errors, etc.)

string

User notifications

string

Debug and process logs

Cookie management messages

Status Types

All responses include a status field:

string

The operation completed successfully

string

An error occurred during the operation

string

The operation is still in progress

Data Models

ChatData

Used for standard chat messages:

{
  "code": "chat",
  "user_id": "user-123",
  "room_id": "product-456",
  "data": {
    "message": "Has anyone reviewed the latest design update?",
    "sender": "user-123",
    "message_id": "msg-789",  // Optional, auto-generated if omitted
    "reply_to": "msg-456",    // Optional, for threaded replies
    "attached_files": ["file-123", "file-456"],  // Optional file IDs
    "metadata": {             // Optional additional context
      "importance": "high",
      "category": "design_review"
    }
  }
}

HaitchChatData

Used for AI assistant chat:

{
  "code": "haitch_chat",
  "user_id": "user-123",
  "room_id": "product-456",
  "data": {
    "message": "What materials would be best for a waterproof enclosure?",
    "sender": "user-123",
    "product_id": "prod-789",  // Optional product context
    "attached_files": ["datasheet.pdf"],  // Optional context files
    "metadata": {               // Optional parameters
      "constraints": ["temperature_resistant", "cost_effective"],
      "industry": "consumer_electronics"
    }
  }
}

DocumentationData

Used for documentation generation:

{
  "code": "documentation",
  "user_id": "user-123",
  "room_id": "product-456",
  "data": {
    "message": "Generate a technical specification for our thermostat",
    "sender": "user-123",
    "doc_type": "technical_specification",  // Document type
    "product_id": "prod-789",
    "attached_files": ["requirements.pdf"],
    "metadata": {
      "document_format": "pdf",
      "sections": ["features", "electrical_specs", "mechanical_specs"]
    }
  }
}

IdeaData

Used for product idea generation:

{
  "code": "idea",
  "user_id": "user-123",
  "room_id": "product-456",
  "data": {
    "message": "Generate ideas for a smart home climate control system",
    "sender": "user-123",
    "constraints": ["energy_efficient", "wireless", "affordable"],
    "target_market": "residential",
    "metadata": {
      "competitive_analysis": true,
      "feature_priority": true
    }
  }
}

EngineeringData

Used for engineering-specific requests (CAD, DFM, etc.):

{
  "code": "engineering",
  "user_id": "user-123",
  "room_id": "product-456",
  "data": {
    "message": "Generate a mounting bracket for the thermostat",
    "sender": "user-123",
    "engineering_type": "cad_generation",  // Type of engineering request
    "product_id": "prod-789",
    "specifications": {
      "dimensions": "100x80x20mm",
      "material": "ABS plastic",
      "mounting_type": "wall_mount"
    },
    "attached_files": ["reference_design.jpg"]
  }
}

SystemData

Used for system messages:

{
  "status": "success",
  "code": "system",
  "user_id": "user-123",
  "timestamp": "2024-05-19T10:30:45Z",
  "data": {
    "message": "System notification text",
    "details": {
      "event_type": "connection_status",
      "additional_info": "Connected to ProductFlo WebSocket server"
    }
  }
}

ErrorData

Used for error responses (following BaseResponse model):

{
  "status": "error",
  "code": "system",
  "user_id": "user-123",
  "room_id": "product-456",  // Optional room context
  "timestamp": "2024-05-19T10:30:45Z",
  "data": {
    "message": "Error message text",
    "details": {
      "error": "Detailed error description",
      "error_code": "SPECIFIC_ERROR_CODE",  // Optional error code
      "errors": [  // Optional validation errors
        {
          "loc": ["data", "message"],
          "msg": "field required",
          "type": "value_error.missing"
        }
      ]
    }
  }
}

NotificationData

Used for user notifications:

{
  "status": "success",
  "code": "notification",
  "user_id": "user-123",
  "timestamp": "2024-05-19T10:30:45Z",
  "data": {
    "title": "Notification Title",
    "message": "Notification message text",
    "priority": "medium",  // "low", "medium", "high", "critical"
    "action_url": "https://productflo.io/notifications/123",  // Optional
    "metadata": {
      "notification_type": "mention",
      "product_id": "prod-789"
    }
  }
}

Common Error Codes

The WebSocket API uses the following error codes:

Error Code	Description
`MESSAGE_CODE_REQUIRED`	Message code is missing
`UNSUPPORTED_MESSAGE_TYPE`	Message code is not recognized
`ROOM_ID_REQUIRED`	Room ID is required for this operation
`VALIDATION_ERROR`	Message data failed validation
`PROCESSING_ERROR`	General error during message processing
`PERMISSION_DENIED`	User lacks permission for requested action
`HAITCH_CHAT_ERROR`	Error in AI chat processing
`DOCUMENTATION_ERROR`	Error in documentation generation
`IDEA_GENERATION_ERROR`	Error in idea generation
`ENGINEERING_ERROR`	Error in engineering-specific operation

Message Data Validation

All messages are validated using Pydantic models in the server implementation. This provides type safety and ensures messages conform to the expected structure. The system will return detailed validation errors if your message format is incorrect:

{
  "status": "error",
  "code": "system",
  "user_id": "user-123",
  "room_id": "product-456",
  "timestamp": "2024-05-19T10:30:45Z",
  "data": {
    "message": "Message validation failed",
    "details": {
      "errors": [
        {
          "loc": ["data", "message"],
          "msg": "field required",
          "type": "value_error.missing"
        }
      ]
    }
  }
}

Usage Examples

Chat Message with Reply

socket.send(JSON.stringify({
  "code": "chat",
  "user_id": "user-123",
  "room_id": "product-456",
  "data": {
    "message": "I agree with the material selection",
    "sender": "user-123",
    "reply_to": "msg-789"
  }
}));

AI Assistant Request with Context

socket.send(JSON.stringify({
  "code": "haitch_chat",
  "user_id": "user-123",
  "room_id": "product-456",
  "data": {
    "message": "Can you suggest improvements to this PCB layout?",
    "sender": "user-123",
    "attached_files": ["pcb_layout.pdf"],
    "metadata": {
      "constraints": ["space_limited", "cost_sensitive"],
      "component_count": "minimize"
    }
  }
}));

Documentation Generation with Format

socket.send(JSON.stringify({
  "code": "documentation",
  "user_id": "user-123",
  "room_id": "product-456",
  "data": {
    "message": "Create a bill of materials for our smart thermostat",
    "sender": "user-123",
    "doc_type": "bom",
    "product_id": "prod-789",
    "metadata": {
      "format": "excel",
      "include_costs": true,
      "include_suppliers": true
    }
  }
}));

API Introduction

Authentication

Core Resources

File Management

AI Features

Integrations

WebSockets

Payments

Message Types

WebSocket Message Types

Base Message Structure

Response Structure

Message Codes (CodeType Enum)

Client-to-Server Message Codes

Server-to-Client Message Codes

System Message Codes

Status Types

Data Models

ChatData

HaitchChatData

DocumentationData

IdeaData

EngineeringData

SystemData

ErrorData

NotificationData

Common Error Codes

Message Data Validation

Usage Examples

Chat Message with Reply

AI Assistant Request with Context

Documentation Generation with Format

​WebSocket Message Types

​Base Message Structure

​Response Structure

​Message Codes (CodeType Enum)

​Client-to-Server Message Codes

​Server-to-Client Message Codes

​System Message Codes

​Status Types

​Data Models

​ChatData

​HaitchChatData

​DocumentationData

​IdeaData

​EngineeringData

​SystemData

​ErrorData

​NotificationData

​Common Error Codes

​Message Data Validation

​Usage Examples

​Chat Message with Reply

​AI Assistant Request with Context

​Documentation Generation with Format

WebSocket Message Types

Base Message Structure

Response Structure

Message Codes (CodeType Enum)

Client-to-Server Message Codes

Server-to-Client Message Codes

System Message Codes

Status Types

Data Models

ChatData

HaitchChatData

DocumentationData

IdeaData

EngineeringData

SystemData

ErrorData

NotificationData

Common Error Codes

Message Data Validation

Usage Examples

Chat Message with Reply

AI Assistant Request with Context

Documentation Generation with Format