Skip to Content
LYNKORIADocs

Quickstart

Create a project, issue a key, install the SDKs, then send your first message and join your first call.

This guide takes a web app from nothing to a working conversation and video call. You need a Lynkoria console account, Node.js 22.12 or later on your backend, and a modern browser.

Create a project and environment

In the Lynkoria console:

  1. Open Projects → New project, and give it a name and slug (for example acme-chat).
  2. On the project’s Environments tab, choose Add environment → staging. Enter the LiveKit key reference your platform team gave you.
  3. In the new environment, turn on Messaging and Presence. Calls is on by default.
  4. Under Allowed origins, add the exact origin your web app runs on, such as http://localhost:5173. Browser connections from any other origin are rejected.
  5. Select Save changes.

An origin is scheme, host and port with no path or trailing slash. http://localhost:5173 and http://127.0.0.1:5173 are different origins.

Create an API key

On the API keys tab, select Create key, choose the staging environment and keep all three scopes. Copy the secret when it is shown: it is displayed only once. Staging keys start with lynk_test_.

Store it in your backend’s environment, never in frontend code:

.env (backend only)
LYNKORIA_API_URL=https://api.lynkoria.com
LYNKORIA_SERVICE_KEY=lynk_test_…

Install the SDKs

npm install @lynkoria/server
npm install @lynkoria/client @lynkoria/react

Release status

The SDKs (v0.1.0) are restricted packages under Guildsman’s @lynkoria scope and have not been published to a registry yet. Until they are, install them from packed tarballs or the monorepo workspace as described in install the SDKs.

Add token endpoints to your backend

Your backend decides who may talk to whom. It authenticates the user with your existing session, then asks Lynkoria for a short-lived token for that user only.

import express from 'express';
import { createLynkoriaServer } from '@lynkoria/server';

const lynkoria = createLynkoriaServer({
  baseUrl: process.env.LYNKORIA_API_URL!,
  serviceKey: process.env.LYNKORIA_SERVICE_KEY!,
});

const app = express();
app.use(express.json());

// Replace requireUser with your own session middleware.
app.post('/api/lynkoria/session', requireUser, async (req, res) => {
  const session = await lynkoria.sessions.messagingToken({
    userId: req.user.id,
    deviceId: String(req.body.deviceId),
  });
  res.json(session); // { token, expiresAt }
});

app.post('/api/lynkoria/conversations', requireUser, async (req, res) => {
  // Check that req.user may message req.body.peerId before creating anything.
  const members = [req.user.id, String(req.body.peerId)].sort();
  const conversation = await lynkoria.conversations.create({
    type: 'dm', // exactly two members; use 'group' for more
    memberIds: members,
    productConversationId: `dm.${members.join('.')}`,
  });
  res.json({ id: conversation.id });
});

app.post('/api/lynkoria/calls/:room/join', requireUser, async (req, res) => {
  const call = await lynkoria.calls.create({
    productCallId: String(req.params.room),
    type: 'group',
  });
  const credentials = await lynkoria.calls.joinToken({
    callId: call.id,
    userId: req.user.id,
    deviceId: String(req.body.deviceId),
    displayName: req.user.name,
  });
  res.json(credentials); // { url, token, identity, expiresAt }
});

conversations.create and calls.create are idempotent on the product IDs you pass, so calling them again for the same pair or room returns the existing resource.

Connect and send a message

Create one client per signed-in user and wrap your app in LynkoriaProvider:

app.tsx
import { createLynkoria } from '@lynkoria/client';
import { LynkoriaProvider, useConversation } from '@lynkoria/react';
import { useMemo, useState } from 'react';

const deviceId = crypto.randomUUID();
const post = async <T,>(path: string, body: unknown): Promise<T> => {
  const res = await fetch(path, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    credentials: 'same-origin',
    body: JSON.stringify(body),
  });
  if (!res.ok) throw new Error(`Request failed: ${res.status}`);
  return res.json() as Promise<T>;
};

export function App({ userId }: { userId: string }) {
  const client = useMemo(
    () =>
      createLynkoria({
        baseUrl: 'https://api.lynkoria.com',
        getMessagingToken: () => post('/api/lynkoria/session', { deviceId }),
      }),
    [userId], // a new user gets a new client
  );
  return (
    <LynkoriaProvider client={client}>
      <Chat peerId="bob" />
    </LynkoriaProvider>
  );
}

function Chat({ peerId }: { peerId: string }) {
  const [conversationId, setConversationId] = useState<string | null>(null);
  if (!conversationId)
    return (
      <button
        onClick={async () =>
          setConversationId(
            (await post<{ id: string }>('/api/lynkoria/conversations', { peerId })).id,
          )
        }
      >
        Chat with {peerId}
      </button>
    );
  return <Messages id={conversationId} />;
}

function Messages({ id }: { id: string }) {
  const { messages, send, loading } = useConversation(id);
  const [text, setText] = useState('');
  if (loading) return <p>Loading…</p>;
  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        void send(text);
        setText('');
      }}
    >
      <ol>
        {messages.map((m) => (
          <li key={m.id}>
            <b>{m.senderId}</b>: {m.deletedAt ? 'Message deleted' : m.body}
          </li>
        ))}
      </ol>
      <input value={text} onChange={(e) => setText(e.target.value)} />
    </form>
  );
}

Sign in as two different users in two browser profiles. Messages appear in both instantly, and after a refresh they load from history.

Join a video call

call.tsx
import { RoomContext, VideoConference } from '@livekit/components-react';
import '@livekit/components-styles';
import { useCall } from '@lynkoria/react';
// `post` is the same helper as in step 5.

export function Call({ room, deviceId }: { room: string; deviceId: string }) {
  const call = useCall();
  if (!call.session)
    return (
      <button
        disabled={call.state === 'connecting'}
        onClick={() =>
          call.join({ getJoinToken: () => post(`/api/lynkoria/calls/${room}/join`, { deviceId }) })
        }
      >
        Join {room}
      </button>
    );
  return (
    <RoomContext.Provider value={call.session.room}>
      <VideoConference />
      <button onClick={() => void call.leave()}>Leave</button>
    </RoomContext.Provider>
  );
}

Install the LiveKit UI packages for the prebuilt layout: npm install @livekit/components-react @livekit/components-styles livekit-client. Browsers only grant camera and microphone access on https:// origins or localhost.

Check it worked

Open your project’s Analytics tab in the console. Within about 15 seconds you will see tokens issued, messages sent and API requests. Calls count when a room is created, and participant minutes appear when each participant leaves.

Try it in the Playground

The Lynkoria Playground is a ready-made test app that exercises every feature against a real project: messaging, calls, livestreams, screen sharing and presence, with a live log of every SDK call, socket event and media event. Your platform team runs it with a staging key; see run the platform locally to run it yourself.

Next steps

On this page