Identities and presence

Identities

An identity is a string you choose for a person — app:user:123, agent:7, guest:9f3a… — up to 200 characters. Talkline compares it exactly and never interprets it. Anything you know about the person stays with you; what Talkline needs, you tell it:

await talkline.identities.upsert('agent:7', {
  displayName: 'Rina',
  availability: 'available',
  metadata: { team: 'billing' },
});

PUT /v1/identities/{identity} creates the record or replaces it: a field you leave out goes back to its default — no display name, available, empty metadata. Send all three every time. Call it when a person signs in and when their availability changes. What others in a room see as a participant's name is the name in that participant's access token, not this record.

Availability is what the person chose: available, away or dnd. An identity that never chose is available. Queues offer calls only to available members, from the moment you change it. A client watching presence sees each identity's availability with its state, and hears a change made through this API at once — a PUT that leaves it as it was tells them nothing.

Presence

Presence is what Talkline sees: whether an identity has a connected client.

State	Meaning
offline	No connected client.
online	At least one connected client.
in_call	Connected, and in a call.

From your backend:

const [rina] = await talkline.presence.get(['agent:7']); // { identity, state, availability, lastSeenAt }
for await (const p of talkline.presence.iterateOnline()) console.log(p.identity, p.state);

From a client, watch up to 200 identities and hear of each change:

const now = await client.watchPresence(['agent:7', 'agent:9']);
client.on('presence', (p) => updateContact(p.identity, p.state, p.availability));

Watches survive reconnects; after one, presence fires again for every watched identity, in case a change was missed while the client was away.

A client can set its own person's availability, as your backend's PUT does — for an agent's Away switch, say:

await client.setAvailability('away'); // 'available', 'away' or 'dnd'

It is the identity's, not the tab's: it outlives the session, and everyone watching hears of it at once. Your backend's next PUT replaces it, so send the person's current choice there too.

Who can see and call whom

Talkline does not decide who may know about whom inside your application. Any connected client may watch the presence of any identity of your application, 200 at a time, and any client whose token carries roomCreate may call any identity of it. Your application is the boundary: no client sees or reaches another application's identities.

If your product needs a narrower rule — a customer who may call only their own agent — keep roomCreate off that client's token and place the call from your backend (POST /v1/calls), where your own rules decide. A client needs no grant to answer a call placed for it, only roomJoin.

Devices

PUT /v1/identities/{identity}/devices/{deviceId} registers a device's push token, so a call can ring a phone whose app is not open. Push arrives with the mobile SDKs. A web-only product does not need devices; in the meantime, a call to someone with no connected client is announced to your backend by call.ringing with needsPush: true, so you can notify them your own way.