> ## 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.

# Chat Communication

> Real-time chat communication via WebSockets

# WebSocket Chat Communication

The ProductFlo WebSocket API provides robust support for real-time chat communication between users, teams, and AI assistants.

## Chat Message Types

The following message types are used for chat communication:

| Type           | Description               |
| -------------- | ------------------------- |
| `chat`         | Regular chat messages     |
| `typing`       | Typing indicator          |
| `read_receipt` | Message read confirmation |
| `presence`     | User presence updates     |

## Sending Chat Messages

To send a chat message, use the following format:

```json theme={null}
{
  "code": "chat",
  "user_id": "user_456",
  "room_id": "conversation_123",
  "data": {
    "message": "Hello, how's the design coming along?",
    "sender": "user_456",
    "message_id": "msg_abc123",
    "attached_files": ["file_789"]
  }
}
```

### Required Fields

* `code`: Must be "chat"
* `user_id`: The user ID of the sender
* `room_id`: The conversation or room ID
* `data.message`: The text message content
* `data.sender`: The user ID of the sender (same as `user_id`)

### Optional Fields

* `data.message_id`: Unique ID for the message (auto-generated if not provided)
* `data.attached_files`: Array of file IDs attached to the message
* `data.reply_to`: ID of the message being replied to
* `timestamp`: ISO format timestamp (auto-generated if not provided)

## Receiving Chat Messages

When a chat message is received, it will have the following format:

```json theme={null}
{
  "status": "success",
  "code": "chat_response",
  "user_id": "user_456",
  "room_id": "conversation_123",
  "timestamp": "2023-05-01T12:34:56.789Z",
  "data": {
    "message": "Hello, how's the design coming along?",
    "sender": "user_456",
    "message_id": "msg_xyz",
    "attached_files": [],
    "metadata": {
      "sent_from_device": "web"
    }
  }
}
```

## Typing Indicators

To indicate that a user is typing, send a message with the `RoomStatus.TYPING` code:

```json theme={null}
{
  "code": "typing",
  "user_id": "user_456",
  "room_id": "conversation_123",
  "data": {
    "status": "started", // or "stopped"
    "sender": "user_456"
  }
}
```

## Read Receipts

To mark a message as read, send a message with the `RoomStatus.READ_RECEIPT` code:

```json theme={null}
{
  "code": "read_receipt",
  "user_id": "user_456",
  "room_id": "conversation_123",
  "data": {
    "message_id": "msg_xyz",
    "sender": "user_456"
  }
}
```

## Presence Updates

To update user presence status, send a message with the `RoomStatus.PRESENCE` code:

```json theme={null}
{
  "code": "presence",
  "user_id": "user_456",
  "data": {
    "status": "online", // online, offline, away, busy
    "sender": "user_456"
  }
}
```

## Conversation Rooms

Chat messages are organized into rooms based on the conversation ID. When joining a conversation, you should:

1. Join the conversation room:
   ```json theme={null}
   {
     "code": "join",
     "user_id": "user_456",
     "room_id": "conversation_123",
     "data": {}
   }
   ```

2. Request history messages (optional):
   ```json theme={null}
   {
     "code": "historic",
     "user_id": "user_456",
     "room_id": "conversation_123",
     "data": {
       "message": "Load conversation history",
       "product_id": "product_789",
       "conversation_id": "conversation_123"
     }
   }
   ```

3. Update your presence:
   ```json theme={null}
   {
     "code": "presence",
     "user_id": "user_456",
     "room_id": "conversation_123",
     "data": {
       "sender": "user_456",
       "status": "online"
     }
   }
   ```

## Message Metadata

Chat messages can include metadata for additional context:

```json theme={null}
{
  "code": "chat",
  "user_id": "user_456",
  "room_id": "conversation_123",
  "data": {
    "message": "Check out these design specs",
    "sender": "user_456",
    "metadata": {
      "importance": "high",
      "category": "design_review",
      "tags": ["urgent", "review"]
    }
  }
}
```

## File Attachments

To send a message with file attachments:

1. First upload the files using the `/files` API endpoint
2. Then include the file IDs in the chat message:
   ```json theme={null}
   {
     "code": "chat",
     "user_id": "user_456",
     "room_id": "conversation_123",
     "data": {
       "message": "Here are the updated CAD files",
       "sender": "user_456",
       "attached_files": ["file_123", "file_456"]
     }
   }
   ```

## Broadcast Messages

To send a message to multiple rooms, use a server-side broadcast through the API. Clients cannot directly broadcast messages for security reasons.