Skip to Content
LYNKORIADocs

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');
TypeMembersNotes
dmExactly 2, fixedRequires Direct messages in messaging policy.
group1–1000 per request, changeableRequires Group conversations in policy.
channelLike groupFor broadcast-style rooms; same policy as groups.
sessionLike groupFor 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 page

history() 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 URL

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

On this page