Messaging
Create conversations, send and receive ordered messages, load history, and add edits, reactions, receipts, typing and attachments.
Enable Messaging for the environment in the console. Messages are stored durably in order; the realtime socket delivers them instantly, and history fills any gap.
Create conversations on your backend
Users cannot create conversations or add themselves. Your backend does it after applying your own rules:
// One-to-one
const dm = await lynkoria.conversations.create({
type: 'dm',
memberIds: ['alice', 'bob'],
productConversationId: 'dm.alice.bob',
});
// Group
const team = await lynkoria.conversations.create({
type: 'group',
tenantId: 'workspace-42',
title: 'Design team',
memberIds: ['alice', 'bob', 'carol'],
productConversationId: 'team-design',
});
await lynkoria.conversations.addMembers(team.id, ['dave']);
await lynkoria.conversations.removeMember(team.id, 'dave');| Type | Members | Notes |
|---|---|---|
dm | Exactly 2, fixed | Requires Direct messages in messaging policy. |
group | 1–1000 per request, changeable | Requires Group conversations in policy. |
channel | Like group | For broadcast-style rooms; same policy as groups. |
session | Like group | For conversations tied to a call or event. |
Creating with the same productConversationId returns the existing conversation. Return the Lynkoria id (a UUID) to your app; the client SDK uses that ID, not your product ID.
Send and receive
import { useConversation } from '@lynkoria/react';
function Thread({ id }: { id: string }) {
const { messages, send, loading, error, hasMore, loadOlder } = useConversation(id);
if (loading) return <p>Loading…</p>;
if (error) return <p role="alert">Could not load messages.</p>;
return (
<>
{hasMore && <button onClick={() => void loadOlder()}>Load older</button>}
{messages.map((m) => (
<p key={m.id}>
{m.senderId}: {m.deletedAt ? 'Message deleted' : m.body}
{m.editedAt && ' (edited)'}
</p>
))}
<button onClick={() => void send('Hello, team')}>Send</button>
</>
);
}useConversation loads history, applies realtime events in order, deduplicates them and resyncs after gaps or reconnects. Render message text as text, never as HTML.
Retries never duplicate
Every send carries a clientMessageId. Sending again with the same ID returns the original message instead of creating a second one. If a send times out, retry with the same ID. A new ID means a new message.
History and ordering
Each conversation change gets the next sequence number (seq). Messages keep their original seq; edits, deletes and reactions get their own later sequence numbers as events.
await client.messages.history(conversationId, { beforeSeq: oldestSeq, limit: 50 }); // older pagehistory() without beforeSeq returns the latest messages as snapshots and starts ordered tracking. The SDK then requests after_seq change events to catch up. Snapshots and change events are different lists; do not merge them by hand unless you use the exported applyEvent and mergeHistory helpers.
Edit, delete and react
await client.messages.edit(messageId, 'Updated text');
await client.messages.delete(messageId);
await client.messages.react(messageId, '👍');
await client.messages.unreact(messageId, '👍');Users can edit and delete their own messages. Reactions require Reactions in the messaging policy. Every change arrives on other devices as message.updated, message.deleted, reaction.added or reaction.removed, and useConversation applies it.
Receipts, reactions and typing
// Mark everything up to a sequence as read (monotonic: it never moves backwards)
await client.messages.markRead(conversationId, latestSeq); // or markRead() from useConversation
client.onRead(({ conversationId, userId, seq }) => {
/* show "seen" up to seq for userId */
});
// Typing: throttled to one event per 3 s; others see it for about 6 s
client.typing.start(conversationId);
client.typing.stop(conversationId);
// React: const typingUserIds = useTyping(conversationId) from '@lynkoria/react'Typing indicators are best-effort and never stored.
Threads
Pass parentMessageId to reply in a thread. Enable Threaded replies in the messaging policy first.
await send('Agreed', { parentMessageId: rootMessage.id });Attachments
Enable Attachments both as an environment feature and in the messaging policy, and make sure the platform team has configured storage CORS for your origin.
const attachment = await client.attachments.upload(conversationId, file, file.name);
await send('Here is the file', { attachmentIds: [attachment.id] });
const { url } = await client.attachments.downloadUrl(attachment.id); // short-lived signed URLUploads go straight to storage with a presigned URL, then Lynkoria verifies the file’s size and type against the policy (default limit 25 MB; default types image/*, video/mp4, application/pdf). Only conversation members can get download URLs.
Attachments are not scanned for malware in v1. Restrict allowed file types, and complete a security review before accepting untrusted documents.
Listing conversations
const { items, nextCursor } = await client.conversations.list({ limit: 20 });Each item includes lastSeq, lastMessageAt and the user’s readSeq, so you can compute unread counts as lastSeq - readSeq.
Retention
Set Message retention in the messaging policy to delete messages older than N days. Expired messages are removed from every connected and reconnecting client in order. Leave it empty to keep messages indefinitely.