> ## Documentation Index
> Fetch the complete documentation index at: https://docs.productflo.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Message Types
> WebSocket message types and formats
# 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:
```json theme={null}
{
"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:
```json theme={null}
{
"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
Standard chat messages
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.)
User notifications
Debug and process logs
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:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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.):
```json theme={null}
{
"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:
```json theme={null}
{
"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):
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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
```javascript theme={null}
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
```javascript theme={null}
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
```javascript theme={null}
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
}
}
}));
```