Video and audio calls
Create a call on your backend, join it from the browser, control the microphone and camera, and leave or end it.
Calls run on LiveKit media servers managed by Lynkoria. Your backend creates the room and issues join tokens; the browser connects with @lynkoria/client.
Create the call on your backend
const call = await lynkoria.calls.create({
productCallId: 'appointment-8812', // your ID; makes creation idempotent
type: 'one_to_one', // 'one_to_one' | 'group' | 'livestream'
tenantId: 'clinic-42', // optional
maxParticipants: 2, // optional, capped by the environment quota
});Creating an active call again with the same productCallId returns the existing call, so every participant’s request can safely call create. Using that ID from a different tenant is rejected. Rooms close automatically after emptyTimeoutSec (default 300 seconds) with nobody in them.
Issue a join token for each participant
const credentials = await lynkoria.calls.joinToken({
callId: call.id,
userId: user.id,
deviceId,
displayName: user.name,
});
// Send credentials ({ url, token, identity, expiresAt }) to this user only.Authorize the user for this call first. The token is valid for 5 minutes to connect; once connected, the session continues.
Join from the browser
import { useCall } from '@lynkoria/react';
function JoinButton({ callKey }: { callKey: string }) {
const call = useCall();
return (
<button
disabled={call.state === 'connecting'}
onClick={() =>
call.join({
getJoinToken: async () => {
const res = await fetch(`/api/calls/${callKey}/token`, { method: 'POST' });
if (!res.ok) throw new Error('Join denied');
return res.json();
},
})
}
>
{call.state === 'connecting' ? 'Connecting…' : 'Join call'}
</button>
);
}useCall leaves the room automatically when the component unmounts, and cancels a join that is superseded by another.
Render participants
session.room is a LiveKit Room. The quickest option is LiveKit’s prebuilt UI:
import { RoomContext, VideoConference } from '@livekit/components-react';
import '@livekit/components-styles';
import { useCall } from '@lynkoria/react';
export function Room() {
const call = useCall();
if (!call.session) return null;
return (
<RoomContext.Provider value={call.session.room}>
<VideoConference />
</RoomContext.Provider>
);
}For a custom layout, use GridLayout, ParticipantTile, useTracks and RoomAudioRenderer from @livekit/components-react, or attach tracks to your own <video> and <audio> elements. Always render a RoomAudioRenderer (or attach audio tracks yourself), and show LiveKit’s StartAudio button where browsers block autoplay.
The prebuilt VideoConference includes a chat panel that uses LiveKit data messages. Lynkoria disables data publishing, so use Lynkoria messaging for in-call chat.
Microphone and camera
| Action | Call |
|---|---|
| Mute or unmute | session.setMicrophoneEnabled(bool) |
| Camera on or off | session.setCameraEnabled(bool) |
| Share screen | session.startScreenShare() |
| Stop sharing | session.stopScreenShare() |
| Watch connection state | session.onStateChange(listener) |
| List devices | session.listDevices('audioinput') |
| Switch device | session.switchDevice(kind, id) |
| Watch participants | session.onParticipantsChange(fn) |
States are connecting, connected, reconnecting and disconnected. Device calls can reject with the browser’s NotAllowedError (permission denied) or NotFoundError (no device); show a clear message and let the user retry. Pass roomOptions and connectOptions to join for anything else LiveKit supports.
Participant snapshots carry mute, camera, screen-share, speaking and connectionQuality state, so a call UI can show who joined or left and warn about a poor connection without listening to raw LiveKit events. In React, use useCallParticipants(call.session).
Ringing and invitations
To ring someone’s other devices before they join, send a call signal from your backend. Online devices receive it on the socket:
await lynkoria.calls.signal(call.id, { type: 'invited', toUserIds: ['bob'], fromUserId: 'alice' });client.onCallStateChange((event) => {
// event.type: 'invited' | 'ringing' | 'accepted' | 'declined' | 'ended'
});Signals reach only connected devices. Push notifications and native incoming-call screens for backgrounded apps remain your product’s responsibility.
Leave versus end
session.leave()(orcall.leave()) disconnects this device only.lynkoria.calls.end(call.id)on your backend ends the call for everyone and stops new tokens.
Usage
Each created call counts once in Calls created. Participant minutes are recorded when each participant session closes, split across UTC days. See the console’s Analytics tab.