Complete chat and messaging system with conversations (direct, group, channel), threaded messages, reactions, read receipts, pinned messages, attachments, mentions, typing indicators, full-text search, and comprehensive moderation tools.

nself plugin run chat init
nself plugin run chat server

All endpoints support multi-app isolation via X-Source-Account-Id header.

Each attachment in the attachments JSONB array has the following structure:

Reactions are stored as a JSONB map on each message where keys are emoji strings and values are arrays of user IDs. Example:

{
  "thumbsup": ["user123", "user456"],
  "heart": ["user789"]
}

Adding a reaction that already exists for a user is idempotent. Removing the last user from an emoji key deletes the key entirely.

Messages support two threading fields:

• reply_to_id -- References the specific message being replied to (inline reply)
• thread_root_id -- References the root message of a thread (groups all replies under one parent)

Use GET /v1/conversations/:id/threads/:msgId to fetch all messages in a thread by passing the root message ID.

Messages can be edited within the configured edit window (CHAT_EDIT_WINDOW_MINUTES). When a message is edited:

1. The original content is preserved in metadata.original_content
2. The edited_at timestamp is set
3. The content field is updated to the new text

The edit window is enforced server-side. If CHAT_EDIT_WINDOW_MINUTES is 0, editing is unlimited. The sender_id query parameter must match the original sender.

Deleting a message is a soft delete:

• The deleted_at timestamp is set
• The content is replaced with [deleted]
• The message record remains in the database for audit purposes

Moderators can delete any message via POST /v1/moderate with action: "delete_message", which replaces content with [deleted by moderator].

When a message is sent, unread counts are incremented for all participants in the conversation except the sender. When a user marks a conversation as read via POST /v1/conversations/:id/read:

1. The last_read_message_id and last_read_at are updated
2. The unread_count is recalculated by counting messages after the read position

The search endpoint supports multiple filters that can be combined:

Unique constraint on (conversation_id, user_id). Re-adding a removed participant clears left_at via upsert.

Unique constraint on (conversation_id, user_id). Upserted on each read receipt update.

Standard webhook event tracking table with id, source_account_id, event_type, payload (JSONB), processed, processed_at, error, created_at.

The schema creates the following indexes for query performance:

Messages not appearing -- Verify the conversation ID is correct and the sender is a participant. Check message content length against CHAT_MAX_MESSAGE_LENGTH.

Edit window expired -- The server enforces CHAT_EDIT_WINDOW_MINUTES from the message's created_at. Increase the value or set to 0 for unlimited editing.

Participant not found -- Participants with left_at set are not returned by default. Re-adding a removed participant clears left_at via upsert.

Pinned message limit reached -- The server enforces CHAT_MAX_PINNED per conversation. Unpin existing messages before pinning new ones.

Unread count incorrect -- Run POST /v1/conversations/:id/read with the latest last_read_message_id to recalculate. Unread counts are incremented on each new message and recalculated on each read receipt update.

Search returns no results -- Search uses case-insensitive ILIKE matching. Deleted messages (with deleted_at set) are still returned in search results. Use the from_date and to_date filters to narrow the time range.

Reactions not updating -- Reactions are stored as a JSONB map on the message record. Adding the same reaction twice for the same user is idempotent. The emoji in the DELETE URL must be URL-encoded.