​
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

​
chat
string
Standard chat messages
​
haitch_chat
string
Messages for the Haitch AI assistant
​
idea
string
Product idea generation requests
​
documentation
string
Documentation generation requests
​
engineering
string
Engineering-specific requests (CAD, DFM, etc.)

​
Server-to-Client Message Codes

​
chat_response
string
Response to standard chat messages
​
idea_response
string
Response to idea generation requests
​
documentation_response
string
Response to documentation generation requests
​
engineering_response
string
Response to engineering-specific requests

​
System Message Codes

​
system
string
System messages (connection status, errors, etc.)
​
notification
string
User notifications
​
logs
string
Debug and process logs
​
cookie
string
Cookie management messages

​
Status Types

All responses include a status field:
​
success
string
The operation completed successfully
​
error
string
An error occurred during the operation
​
pending
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 CodeDescription
MESSAGE_CODE_REQUIREDMessage code is missing
UNSUPPORTED_MESSAGE_TYPEMessage code is not recognized
ROOM_ID_REQUIREDRoom ID is required for this operation
VALIDATION_ERRORMessage data failed validation
PROCESSING_ERRORGeneral error during message processing
PERMISSION_DENIEDUser lacks permission for requested action
HAITCH_CHAT_ERRORError in AI chat processing
DOCUMENTATION_ERRORError in documentation generation
IDEA_GENERATION_ERRORError in idea generation
ENGINEERING_ERRORError 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
    }
  }
}));