Concepts

The handful of nouns everything else is built from.

Application and API key

Your application is your tenancy in a Talkline deployment. Everything you create — rooms, calls, queues, webhook endpoints, identities — belongs to it and is invisible to every other application.

An application has one or more API keys. A key (tlk_live_…) and its secret authenticate your backend to the control API and sign the access tokens your clients connect with. Keys can be created and revoked without downtime by the operator: mint with the new one, then revoke the old. Revoking a key disconnects the clients whose tokens it signed; each reconnects with a token from your token endpoint, now signed with the new key, and keeps its call. A client that can only get a token from the revoked key stays out.

Identity

An identity is a string your backend chooses for a person, up to 200 characters: app:user:123, agent:7, guest:9f3a…. Talkline never resolves it, never asks what it means, and compares it exactly. The same person on two devices is one identity with two connections, and a call to that identity rings both.

Choose a format that never reuses a string for a different person. A guest is simply an identity with no account behind it — guest: plus a random UUID — and needs no special handling anywhere.

Access token

An access token is a JWT your backend signs with your API secret. It says which identity a client is, what it may do (its grants), and nothing about how long its session lasts: it is a ticket to connect, valid for at most ten minutes, and spent on use. The session it opens lasts as long as the client stays connected. Access tokens.

Grants

What a token's holder may do: join rooms, create them, publish microphone or camera, act as a room's admin, stay hidden. Grants are fixed into a participant when it takes its seat; minting a wider token later does not widen a participant already in a room. The grants table.

Room

A room is where media flows. Every call happens in a room, and a room can also be joined directly, by name — a standing meeting, a classroom, a link someone shares.

A room has a mode, fixed for its life:

• p2p — exactly two seats. Media goes directly between the two clients when the network allows, and through a TURN relay when it does not. A one-to-one call is a p2p room.
• sfu — up to 100 seats. Every client sends its media once to Talkline's media server, which forwards it to the others, choosing a lower resolution for a small tile and pausing a video nobody can see. A room joined by name is an sfu room.

A room has a sid (RM_…) and optionally a name, unique among your live rooms. It ends after it has been empty for its empty timeout (60 seconds by default), and its name is then free again.

Participant and track

A participant is one identity's seat in one room (PT_…). It carries the identity, a display name, your metadata, and its grants.

A track is one stream of media a participant publishes (TR_…): its microphone, its camera, a screen share. A track has a kind (audio, video) and a source (microphone, camera, screen, screen_audio).

Call and invite

A call is a room plus the act of ringing someone into it (CS_…). The caller is seated at once; each identity called gets an invite, which rings every connected client of that identity until one answers, the caller cancels, or the ring timeout passes.

A call has a status — ringing, active, then one of completed, no_answer, rejected, cancelled or failed — and, once over, an end reason and a duration. A call can be placed by a client (A one-to-one call) or by your backend (POST /v1/calls).

Queue

A queue routes a call to whichever of its members is free: the caller calls the queue, and Talkline rings one eligible member at a time until one answers. Members are identities; eligibility is presence, chosen availability, skills and whether they are already in a call. A queue call.

Session

A session is one client's connection to the signaling server, and it outlives the socket under it: a client whose network drops has fifteen minutes to reconnect and resume where it was, in the same room and the same call, without anyone else noticing more than a frozen frame. Connection and recovery.

Metadata

Rooms, participants, tokens, calls and identities each carry metadata: a JSON object of your own, at most 4 096 bytes. Talkline stores it and sends it to the clients that should see it, and never reads it. It is where your product's meaning goes — a ticket id, a topic, a role — because Talkline has no field for any of those.

WARNING

A participant cannot change its own metadata unless its token carries canUpdateOwnMetadata. If you write a role into participant metadata, leave that grant off: otherwise any participant could promote itself.