Documentation

    Concepts, value, and typical clone scenarios — less code.

    Welcome to Ring
    Quick Reference
    Getting Started
    Prerequisites
    Installation
    First Success Validation
    Next Steps
    Features
    Multi-Vendor Store
    Inventory & Stock
    Vendor Management
    Commissions & Settlements
    SubscriptionConductor
    PaymentConductor
    Payments Overview
    Public Pools & DAO Jars
    WayForPay Payment Integration
    Wallet & Credit System
    WalletConductor
    Affiliate & Referral Enablement
    Referral Codes (Refcodes)
    NFT Exhibition Marketplace
    Solana NFT Gates
    Token Staking System
    Owner Project Lab
    Entities
    Opportunities
    Real-Time Messaging
    Ring Tasks
    WebRTC Calls & STUNner TURN
    Peer Games
    News Module
    Member Blogs
    Public Profile Pages
    Ring File Cabinet
    Username Reservation System
    Scientific Editor
    Notifications
    Push Notifications with FCM (Ring-Powered)
    Email AI-CRM
    Ring Mailer & RingdomX Mail
    Tunnel Protocol
    VideoConductor
    MediaConductor
    Generative Gallery
    Authentication
    Security & Compliance
    Admin console
    Admin Wiki
    Manage via Telegram
    Locale System
    Mobile Experience
    Performance Optimization Patterns
    Examples
    Quick Start
    Basic Setup
    White Label
    Custom Branding
    Web3 Integration
    Real World
    Advanced Features
    Customization
    Quick Start — Your First Ring Clone
    Customization Guide
    Branding
    Themes
    Features
    Localization
    Token Economics Setup
    Payment Gateway Integration
    Reference Ring deployments
    Web3
    Token launch jurisdictions
    Wallet
    Wallet Security Tips
    Integrations
    Ethereum wallets (Wagmi v3)
    RingFileBase (object storage API)
    Ring CDN (RingFileBase edge)
    Deployment
    Self-hosted deployment
    Vercel
    Docker
    Environment Configuration
    Monitoring & Analytics
    Performance Optimization
    Backup & Recovery
    Architecture
    Data Model
    Security
    Real Time
    Discovery Mutation Sync
    PaymentConductor architecture
    WalletConductor architecture
    Development
    Ring MCP Server

    Quick entry (CTOs · auditors · agents)

    Welcome — mission & audiences
    Quick Reference
    Getting started
    Architecture & Auth.js
    Backend modes & databases (DB_BACKEND_MODE)
    Self-hosted
    Ring MCP Tools
    Ring MCP Server
    Token economics
    Token launch jurisdictions
    Deploy (Docker · k8s)
    Security & compliance reads
    ringdom.org — LegioX homebase
    Source — MIT license (GitHub)

    Documentation

    Concepts, value, and typical clone scenarios — less code.

    Welcome to Ring
    Quick Reference
    Getting Started
    Prerequisites
    Installation
    First Success Validation
    Next Steps
    Features
    Multi-Vendor Store
    Inventory & Stock
    Vendor Management
    Commissions & Settlements
    SubscriptionConductor
    PaymentConductor
    Payments Overview
    Public Pools & DAO Jars
    WayForPay Payment Integration
    Wallet & Credit System
    WalletConductor
    Affiliate & Referral Enablement
    Referral Codes (Refcodes)
    NFT Exhibition Marketplace
    Solana NFT Gates
    Token Staking System
    Owner Project Lab
    Entities
    Opportunities
    Real-Time Messaging
    Ring Tasks
    WebRTC Calls & STUNner TURN
    Peer Games
    News Module
    Member Blogs
    Public Profile Pages
    Ring File Cabinet
    Username Reservation System
    Scientific Editor
    Notifications
    Push Notifications with FCM (Ring-Powered)
    Email AI-CRM
    Ring Mailer & RingdomX Mail
    Tunnel Protocol
    VideoConductor
    MediaConductor
    Generative Gallery
    Authentication
    Security & Compliance
    Admin console
    Admin Wiki
    Manage via Telegram
    Locale System
    Mobile Experience
    Performance Optimization Patterns
    Examples
    Quick Start
    Basic Setup
    White Label
    Custom Branding
    Web3 Integration
    Real World
    Advanced Features
    Customization
    Quick Start — Your First Ring Clone
    Customization Guide
    Branding
    Themes
    Features
    Localization
    Token Economics Setup
    Payment Gateway Integration
    Reference Ring deployments
    Web3
    Token launch jurisdictions
    Wallet
    Wallet Security Tips
    Integrations
    Ethereum wallets (Wagmi v3)
    RingFileBase (object storage API)
    Ring CDN (RingFileBase edge)
    Deployment
    Self-hosted deployment
    Vercel
    Docker
    Environment Configuration
    Monitoring & Analytics
    Performance Optimization
    Backup & Recovery
    Architecture
    Data Model
    Security
    Real Time
    Discovery Mutation Sync
    PaymentConductor architecture
    WalletConductor architecture
    Development
    Ring MCP Server

    Quick entry (CTOs · auditors · agents)

    Welcome — mission & audiences
    Quick Reference
    Getting started
    Architecture & Auth.js
    Backend modes & databases (DB_BACKEND_MODE)
    Self-hosted
    Ring MCP Tools
    Ring MCP Server
    Token economics
    Token launch jurisdictions
    Deploy (Docker · k8s)
    Security & compliance reads
    ringdom.org — LegioX homebase
    Source — MIT license (GitHub)

    Documentation

    Concepts, value, and typical clone scenarios — less code.

    Welcome to Ring
    Quick Reference
    Getting Started
    Prerequisites
    Installation
    First Success Validation
    Next Steps
    Features
    Multi-Vendor Store
    Inventory & Stock
    Vendor Management
    Commissions & Settlements
    SubscriptionConductor
    PaymentConductor
    Payments Overview
    Public Pools & DAO Jars
    WayForPay Payment Integration
    Wallet & Credit System
    WalletConductor
    Affiliate & Referral Enablement
    Referral Codes (Refcodes)
    NFT Exhibition Marketplace
    Solana NFT Gates
    Token Staking System
    Owner Project Lab
    Entities
    Opportunities
    Real-Time Messaging
    Ring Tasks
    WebRTC Calls & STUNner TURN
    Peer Games
    News Module
    Member Blogs
    Public Profile Pages
    Ring File Cabinet
    Username Reservation System
    Scientific Editor
    Notifications
    Push Notifications with FCM (Ring-Powered)
    Email AI-CRM
    Ring Mailer & RingdomX Mail
    Tunnel Protocol
    VideoConductor
    MediaConductor
    Generative Gallery
    Authentication
    Security & Compliance
    Admin console
    Admin Wiki
    Manage via Telegram
    Locale System
    Mobile Experience
    Performance Optimization Patterns
    Examples
    Quick Start
    Basic Setup
    White Label
    Custom Branding
    Web3 Integration
    Real World
    Advanced Features
    Customization
    Quick Start — Your First Ring Clone
    Customization Guide
    Branding
    Themes
    Features
    Localization
    Token Economics Setup
    Payment Gateway Integration
    Reference Ring deployments
    Web3
    Token launch jurisdictions
    Wallet
    Wallet Security Tips
    Integrations
    Ethereum wallets (Wagmi v3)
    RingFileBase (object storage API)
    Ring CDN (RingFileBase edge)
    Deployment
    Self-hosted deployment
    Vercel
    Docker
    Environment Configuration
    Monitoring & Analytics
    Performance Optimization
    Backup & Recovery
    Architecture
    Data Model
    Security
    Real Time
    Discovery Mutation Sync
    PaymentConductor architecture
    WalletConductor architecture
    Development
    Ring MCP Server

    Quick entry (CTOs · auditors · agents)

    Welcome — mission & audiences
    Quick Reference
    Getting started
    Architecture & Auth.js
    Backend modes & databases (DB_BACKEND_MODE)
    Self-hosted
    Ring MCP Tools
    Ring MCP Server
    Token economics
    Token launch jurisdictions
    Deploy (Docker · k8s)
    Security & compliance reads
    ringdom.org — LegioX homebase
    Source — MIT license (GitHub)
    1. Docs
    2. /API
    3. /Messaging API
    Updated Jul 14, 20264 min listen
    Ring Platform Logo

    Завантаження документації...

    Підготовка контенту платформи Ring

    1. Docs
    2. /API
    3. /Messaging API
    Updated Jul 14, 20264 min listen
    Ring Platform Logo

    Завантаження документації...

    Підготовка контенту платформи Ring

    1. Docs
    2. /API
    3. /Messaging API
    Updated Jul 14, 20264 min listen
    Ring Platform Logo

    Завантаження документації...

    Підготовка контенту платформи Ring

    Messaging API

    Ring Platform messaging combines REST routes under /api/conversations with Tunnel Protocol for live message and typing events. Conceptual SSOT for channel vs subtype: Real-Time Messaging.

    Use Founder / Developer tabs in the docs sidebar to filter this page. Older drafts invented a channel conversation type and fabricated SQL — this page matches verified routes and features/chat/types.

    Conversation.type (verified)

    Create and filter use this closed channel enum only:

    direct | entity | opportunity | product | group

    FieldRole
    typeChannel / routing
    metadata.kindOptional subtype (e.g. generative_gallery) — open string today
    metadata.hiddenFromInboxHide from Messages list when true

    Do not send type: 'channel' or type: 'generative'. Tool editors reuse product + kind + hide flags — see Generative Gallery.

    GET /api/conversations ultimately lists via ConversationService.getConversations, which skips isHiddenToolConversation rows (hidden tool chats never pollute the inbox).

    What operators get

    • Members chat in context of deals, entities, and products without leaving your Ring.
    • Generative media history stays in hidden tool threads so Messages stays for people and product agents.
    • Live updates use Tunnel Protocol (WebSocket on k8s; SSE/poll on Vercel).

    Real-Time Messaging

    Channel vs kind taxonomy and inbox hygiene.

    Tunnel Protocol

    WSS / SSE / poll transports.

    Generative Gallery

    Hidden genmedia: product-tool chats.

    Transport

    • Server: publishToChannel('conversation:' + id, …) after writes (lib/tunnel/publisher)
    • Client: useTunnelChannel (hooks/use-tunnel-channel.ts) — not raw useTunnel().subscribe() in effects
    • k8s / self-hosted: native WSS /api/tunnel/ws primary
    • Vercel: SSE + long-poll /api/tunnel/poll
    • Optional Supabase Realtime when configured

    Verified routes

    MethodPathRole
    GET/api/conversationsList conversations (filters; tool chats excluded)
    POST/api/conversationsCreate conversation
    GET/api/conversations/[id]Conversation detail
    PUT

    Related

    Real-Time Messaging

    Feature taxonomy and operator scenarios.

    Tunnel Protocol

    Transport SSOT.

    Generative Gallery

    Hidden product-tool chats.

    WebRTC Calls

    Direct-chat call invite routes.

    Architecture — Real-time

    Messaging API

    Ring Platform messaging combines REST routes under /api/conversations with Tunnel Protocol for live message and typing events. Conceptual SSOT for channel vs subtype: Real-Time Messaging.

    Use Founder / Developer tabs in the docs sidebar to filter this page. Older drafts invented a channel conversation type and fabricated SQL — this page matches verified routes and features/chat/types.

    Conversation.type (verified)

    Create and filter use this closed channel enum only:

    direct | entity | opportunity | product | group

    FieldRole
    typeChannel / routing
    metadata.kindOptional subtype (e.g. generative_gallery) — open string today
    metadata.hiddenFromInboxHide from Messages list when true

    Do not send type: 'channel' or type: 'generative'. Tool editors reuse product + kind + hide flags — see Generative Gallery.

    GET /api/conversations ultimately lists via ConversationService.getConversations, which skips isHiddenToolConversation rows (hidden tool chats never pollute the inbox).

    What operators get

    • Members chat in context of deals, entities, and products without leaving your Ring.
    • Generative media history stays in hidden tool threads so Messages stays for people and product agents.
    • Live updates use Tunnel Protocol (WebSocket on k8s; SSE/poll on Vercel).

    Real-Time Messaging

    Channel vs kind taxonomy and inbox hygiene.

    Tunnel Protocol

    WSS / SSE / poll transports.

    Generative Gallery

    Hidden genmedia: product-tool chats.

    Transport

    • Server: publishToChannel('conversation:' + id, …) after writes (lib/tunnel/publisher)
    • Client: useTunnelChannel (hooks/use-tunnel-channel.ts) — not raw useTunnel().subscribe() in effects
    • k8s / self-hosted: native WSS /api/tunnel/ws primary
    • Vercel: SSE + long-poll /api/tunnel/poll
    • Optional Supabase Realtime when configured

    Verified routes

    MethodPathRole
    GET/api/conversationsList conversations (filters; tool chats excluded)
    POST/api/conversationsCreate conversation
    GET/api/conversations/[id]Conversation detail
    PUT

    Related

    Real-Time Messaging

    Feature taxonomy and operator scenarios.

    Tunnel Protocol

    Transport SSOT.

    Generative Gallery

    Hidden product-tool chats.

    WebRTC Calls

    Direct-chat call invite routes.

    Architecture — Real-time

    Messaging API

    Ring Platform messaging combines REST routes under /api/conversations with Tunnel Protocol for live message and typing events. Conceptual SSOT for channel vs subtype: Real-Time Messaging.

    Use Founder / Developer tabs in the docs sidebar to filter this page. Older drafts invented a channel conversation type and fabricated SQL — this page matches verified routes and features/chat/types.

    Conversation.type (verified)

    Create and filter use this closed channel enum only:

    direct | entity | opportunity | product | group

    FieldRole
    typeChannel / routing
    metadata.kindOptional subtype (e.g. generative_gallery) — open string today
    metadata.hiddenFromInboxHide from Messages list when true

    Do not send type: 'channel' or type: 'generative'. Tool editors reuse product + kind + hide flags — see Generative Gallery.

    GET /api/conversations ultimately lists via ConversationService.getConversations, which skips isHiddenToolConversation rows (hidden tool chats never pollute the inbox).

    What operators get

    • Members chat in context of deals, entities, and products without leaving your Ring.
    • Generative media history stays in hidden tool threads so Messages stays for people and product agents.
    • Live updates use Tunnel Protocol (WebSocket on k8s; SSE/poll on Vercel).

    Real-Time Messaging

    Channel vs kind taxonomy and inbox hygiene.

    Tunnel Protocol

    WSS / SSE / poll transports.

    Generative Gallery

    Hidden genmedia: product-tool chats.

    Transport

    • Server: publishToChannel('conversation:' + id, …) after writes (lib/tunnel/publisher)
    • Client: useTunnelChannel (hooks/use-tunnel-channel.ts) — not raw useTunnel().subscribe() in effects
    • k8s / self-hosted: native WSS /api/tunnel/ws primary
    • Vercel: SSE + long-poll /api/tunnel/poll
    • Optional Supabase Realtime when configured

    Verified routes

    MethodPathRole
    GET/api/conversationsList conversations (filters; tool chats excluded)
    POST/api/conversationsCreate conversation
    GET/api/conversations/[id]Conversation detail
    PUT

    Related

    Real-Time Messaging

    Feature taxonomy and operator scenarios.

    Tunnel Protocol

    Transport SSOT.

    Generative Gallery

    Hidden product-tool chats.

    WebRTC Calls

    Direct-chat call invite routes.

    Architecture — Real-time

    /api/conversations/[id]
    Update conversation
    DELETE/api/conversations/[id]Delete / leave (see route)
    GET, POST/api/conversations/[id]/messagesList / send messages
    POST, GET/api/conversations/[id]/typingTyping signal
    POST, GET/api/conversations/[id]/readMark / read state
    POST/api/conversations/uploadAttachment upload
    POST/api/conversations/[id]/call-inviteWebRTC invite (direct only)
    POST/api/conversations/[id]/call-eventCall signaling event

    GET /api/conversations

    Query params accepted by the route include type (cast to the verified enum above), plus other filter keys wired to ConversationFilters / pagination. Prefer reading app/api/conversations/route.ts for the exact query map — do not assume legacy status=channel samples.

    List results omit conversations where isHiddenToolConversation is true (hiddenFromInbox, kind === 'generative_gallery', or legacy genmedia: / imggen: prefixes on productId / subject).

    POST /api/conversations

    Zod create schema (app/api/conversations/route.ts):

    • type — required enum: direct | entity | opportunity | product | group
    • participantIds — non-empty string array
    • metadata — optional object; required when type !== 'direct'
    • Domain rules: entityId for entity, opportunityId for opportunity, productId for product, groupName (min length) for group
    • Optional tool fields on metadata: kind, hiddenFromInbox, subject, vendorId, …

    Messages

    MethodPathNotes
    GET/api/conversations/[id]/messagesCursor pagination: limit, cursor, direction
    POST/api/conversations/[id]/messagesBody: content + optional type, attachments, message metadata

    Message type values in chat types: text | image | file | system | payment_request | env_request | task | poll | rsvp | dao_jar | share_card (SSOT: MESSAGE_TYPE_ALLOWLIST in features/chat/lib/interactive-kind.ts). Message metadata.kind (e.g. payment_request, gallery_upload) is a different namespace from conversation metadata.kind.

    Modules

    PathRole
    features/chat/types/index.tsConversation, CreateConversationRequest, ConversationFilters
    features/chat/services/conversation-service.tsList/create + isHiddenToolConversation
    features/chat/services/message-service.tsMessages
    app/api/conversations/**HTTP surface
    hooks/use-tunnel-channel.tsClient subscribe SSOT

    Broader realtime topology.

    /api/conversations/[id]
    Update conversation
    DELETE/api/conversations/[id]Delete / leave (see route)
    GET, POST/api/conversations/[id]/messagesList / send messages
    POST, GET/api/conversations/[id]/typingTyping signal
    POST, GET/api/conversations/[id]/readMark / read state
    POST/api/conversations/uploadAttachment upload
    POST/api/conversations/[id]/call-inviteWebRTC invite (direct only)
    POST/api/conversations/[id]/call-eventCall signaling event

    GET /api/conversations

    Query params accepted by the route include type (cast to the verified enum above), plus other filter keys wired to ConversationFilters / pagination. Prefer reading app/api/conversations/route.ts for the exact query map — do not assume legacy status=channel samples.

    List results omit conversations where isHiddenToolConversation is true (hiddenFromInbox, kind === 'generative_gallery', or legacy genmedia: / imggen: prefixes on productId / subject).

    POST /api/conversations

    Zod create schema (app/api/conversations/route.ts):

    • type — required enum: direct | entity | opportunity | product | group
    • participantIds — non-empty string array
    • metadata — optional object; required when type !== 'direct'
    • Domain rules: entityId for entity, opportunityId for opportunity, productId for product, groupName (min length) for group
    • Optional tool fields on metadata: kind, hiddenFromInbox, subject, vendorId, …

    Messages

    MethodPathNotes
    GET/api/conversations/[id]/messagesCursor pagination: limit, cursor, direction
    POST/api/conversations/[id]/messagesBody: content + optional type, attachments, message metadata

    Message type values in chat types: text | image | file | system | payment_request | env_request | task | poll | rsvp | dao_jar | share_card (SSOT: MESSAGE_TYPE_ALLOWLIST in features/chat/lib/interactive-kind.ts). Message metadata.kind (e.g. payment_request, gallery_upload) is a different namespace from conversation metadata.kind.

    Modules

    PathRole
    features/chat/types/index.tsConversation, CreateConversationRequest, ConversationFilters
    features/chat/services/conversation-service.tsList/create + isHiddenToolConversation
    features/chat/services/message-service.tsMessages
    app/api/conversations/**HTTP surface
    hooks/use-tunnel-channel.tsClient subscribe SSOT

    Broader realtime topology.

    /api/conversations/[id]
    Update conversation
    DELETE/api/conversations/[id]Delete / leave (see route)
    GET, POST/api/conversations/[id]/messagesList / send messages
    POST, GET/api/conversations/[id]/typingTyping signal
    POST, GET/api/conversations/[id]/readMark / read state
    POST/api/conversations/uploadAttachment upload
    POST/api/conversations/[id]/call-inviteWebRTC invite (direct only)
    POST/api/conversations/[id]/call-eventCall signaling event

    GET /api/conversations

    Query params accepted by the route include type (cast to the verified enum above), plus other filter keys wired to ConversationFilters / pagination. Prefer reading app/api/conversations/route.ts for the exact query map — do not assume legacy status=channel samples.

    List results omit conversations where isHiddenToolConversation is true (hiddenFromInbox, kind === 'generative_gallery', or legacy genmedia: / imggen: prefixes on productId / subject).

    POST /api/conversations

    Zod create schema (app/api/conversations/route.ts):

    • type — required enum: direct | entity | opportunity | product | group
    • participantIds — non-empty string array
    • metadata — optional object; required when type !== 'direct'
    • Domain rules: entityId for entity, opportunityId for opportunity, productId for product, groupName (min length) for group
    • Optional tool fields on metadata: kind, hiddenFromInbox, subject, vendorId, …

    Messages

    MethodPathNotes
    GET/api/conversations/[id]/messagesCursor pagination: limit, cursor, direction
    POST/api/conversations/[id]/messagesBody: content + optional type, attachments, message metadata

    Message type values in chat types: text | image | file | system | payment_request | env_request | task | poll | rsvp | dao_jar | share_card (SSOT: MESSAGE_TYPE_ALLOWLIST in features/chat/lib/interactive-kind.ts). Message metadata.kind (e.g. payment_request, gallery_upload) is a different namespace from conversation metadata.kind.

    Modules

    PathRole
    features/chat/types/index.tsConversation, CreateConversationRequest, ConversationFilters
    features/chat/services/conversation-service.tsList/create + isHiddenToolConversation
    features/chat/services/message-service.tsMessages
    app/api/conversations/**HTTP surface
    hooks/use-tunnel-channel.tsClient subscribe SSOT

    Broader realtime topology.