Conversations contain the operational support history between Visitors and Team Members. Messages belong to Conversations and can contain text, media, threading information, delivery state, or internal-note metadata.
Conversation Lifecycle
The canonical user-facing Conversation lifecycle contains three states:
OPEN → RESOLVED
OPEN
The Conversation is active and available for ongoing communication.
RESOLVED
The Conversation has been resolved. Resolution can trigger CSAT behavior when enabled.
CLOSED is a legacy persistence value. It is not a current user-facing Conversation lifecycle state. User-facing APIs, dashboard workflows, and current operational behavior use RESOLVED.
Conversation Object
ConversationRoom represents a Conversation.
| Field | Type | Required | Nullable | Default | Description |
| id | string | Yes | No | Generated | Conversation identifier. |
| currentStatus | ConversationStatus | Yes | No | OPEN | Current Conversation lifecycle state. |
| workspaceId | string | Yes | No | — | Owning Workspace. |
| channelId | string | Yes | No | — | Entry-point Channel. |
| guestId | string | Yes | No | — | Visitor associated with the Conversation. |
| agentId | string | No | Yes | null | Assigned Agent, or null when unassigned. |
| isPinned | boolean | Yes | No | false | Whether the Conversation is pinned. |
| pinnedAt | ISO-8601 timestamp | No | Yes | null | Pin timestamp. |
| latestMessageId | string | No | Yes | null | Reference to the latest Message. |
| metadata | ConversationMetadata | No | Yes | null | Structured Conversation metadata. |
| createdAt | ISO-8601 timestamp | Yes | No | Generated | Conversation creation timestamp. |
| updatedAt | ISO-8601 timestamp | Yes | No | Generated | Last activity timestamp. |
Conversation Metadata
ConversationMetadata contains structured information associated with Conversation state and operational context, including supported summary, priority, and resolution metadata.
Message Object
Message represents an individual message in a Conversation.
| Field | Type | Required | Nullable | Default | Description |
| id | string | Yes | No | Generated | Message identifier. |
| conversationId | string | Yes | No | — | Parent Conversation. |
| senderId | string | No | Yes | null | Author User identifier. System-generated messages may not have a sender. |
| content | string | No | Yes | null | Message content. Maximum supported text length is 5,000 characters. |
| type | MessageType | Yes | No | REGULAR | Message category. |
| isInternalNote | boolean | Yes | No | false | Indicates an internal note hidden from Visitors. |
| status | MessageStatus | Yes | No | SENT | Current message delivery state. |
| deliveredAt | ISO-8601 timestamp | No | Yes | null | Delivery timestamp. |
| seenAt | ISO-8601 timestamp | No | Yes | null | Read timestamp. |
| parentId | string | No | Yes | null | Parent message for a threaded reply. |
| mediaId | string | No | Yes | null | Associated media asset identifier. |
| mediaUrl | string | No | Yes | null | Media delivery URL. |
| metadata | MessageMetadata | No | Yes | null | Structured message metadata. |
| createdAt | ISO-8601 timestamp | Yes | No | Generated | Message creation timestamp. |
Message Delivery Lifecycle
PENDING
↓
SENT
↓
DELIVERED
↓
SEEN
SENT / DELIVERED
↓
FAILED
Delivery States
| State | Description |
| PENDING | Client-side optimistic state before server acknowledgment. |
| SENT | Message has been successfully persisted. |
| DELIVERED | Message has been delivered through the supported real-time path. |
| SEEN | Message has been marked as read. |
| FAILED | Message transmission or validation failed. |
Message Types
| Value | Description |
| REGULAR | Standard conversation message. |
| SYSTEM_PROMPT | System-generated event or notification message. |
| AUTOMATED_RESPONSE | Automated response such as a configured welcome or offline message. |
Internal Notes
When isInternalNote is true, the message is an internal note intended for Team Members and is not exposed to the Visitor as a public reply.
Message Metadata
MessageMetadata can contain structured objects such as:
MessageButton
| Field | Type | Description |
| label | string | Button text. |
| url | string | Destination URL. |
MessageAttachment
| Field | Type | Description |
| fileId | string | Uploaded file identifier. |
| fileName | string | File name. |
| fileUrl | string | File access URL. |
| fileType | string | MIME or file type information. |
| fileSize | number | File size. |
MessageSystemEvent
| Field | Type | Description |
| type | string | System event type. |
| actorId | string | User or system actor identifier. |
| actorName | string | Display name of the actor. |
| targetId | string | Target entity identifier where applicable. |
| targetName | string | Target display name where applicable. |
Threading & Attachments
parentId identifies the parent message for threaded replies.
mediaId identifies the associated media asset.
mediaUrl contains the delivery URL associated with the media asset.
Conversation Read State
ConversationReadState tracks per-user read position and unread state.
Typical state information includes:
- conversationId
- userId
- lastSeenAt
- lastSeenMessageId
- unreadCount
- hasUnread
Conversation Assignment Log
ConversationAssignmentLog records Conversation assignment changes.
AssignmentAction values:
- ASSIGNED
- UNASSIGNED
Need Help?
Email: support@ysdesk.com
Documentation: https://docs.ysplugins.com/ys-desk