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
Messages for the Haitch AI assistant
Product idea generation requests
Documentation generation requests
Engineering-specific requests (CAD, DFM, etc.)
Server-to-Client Message Codes
Response to standard chat messages
Response to idea generation requests
Response to documentation generation requests
Response to engineering-specific requests
System Message Codes
System messages (connection status, errors, etc.)
Cookie management messages
Status Types
All responses include a status field:
The operation completed successfully
An error occurred during the operation
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"
}
}
}));
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
}
}
}));
