Presence & BLF

Subscribe to real-time presence updates for other users in the account. This powers busy lamp field (BLF) indicators and contact status displays.

Subscribing

Pass the users to watch: between 1 and 100 user IDs. There is no account-wide subscription, and an empty list or more than 100 IDs throws.

JavaScript

// Subscribe to specific users
phone.subscribePresence([aliceUserId, bobUserId]);

// Or to the users in the directory (up to 100)
const directory = await phone.listDirectory();
const ids = directory.slice(0, 100).map((entry) => entry.user);
if (ids.length > 0) phone.subscribePresence(ids);

// Get initial presence snapshot
phone.on('presenceList', (users) => {
  // [{ userId, name, status, doNotDisturb, statusText, updatedAt }]
  updateBuddyList(users);
});

// Listen for changes
phone.on('presenceUpdate', (update) => {
  // { userId, status, doNotDisturb, statusText, updatedAt }
  updateBuddyListEntry(update);
});

Presence Statuses

status reports what the phone system observes about reachability:

Status	Description
available	User is online and can receive calls
on_call	User is on an active call (set automatically)
offline	No active WebRTC or SIP registration

The PresenceStatus type also includes dnd and away. They are reserved for setting your own status, which isn't available yet (see below), and are not reported today. Handle them anyway so your UI keeps working when they arrive.

Do Not Disturb is a separate field

doNotDisturb is a separate axis from status, not one of its values: a user can be available but decline calls because doNotDisturb is on.

JavaScript

// A registered user who has DND on
{ status: 'available', doNotDisturb: true }

The two answer different questions, which is why we report them side by side rather than folding DND into status:

• doNotDisturb is configuration. Someone turned it on, and it stays on until someone turns it off — across reconnects, restarts, and going offline.
• status is a lossy summary of what the system currently observes. It reduces several signals to one value using the precedence on_call > available > offline, so some detail is deliberately discarded.

That reduction is a product decision, not a technical necessity, and it has a consequence worth knowing if you are driving a BLF display: because on_call takes precedence, a user on a call reports on_call even if their device is no longer registered. Read status as the single best answer to "can I reach this person right now", not as a faithful description of every underlying signal.

status never reports Do Not Disturb; read doNotDisturb for that. The REST presence API (GET /v1/users/{user_id}/presence) reports the same two axes as state and do_not_disturb.

Setting Status and Do Not Disturb

Users can't set their own presence status yet: phone.setPresence() exists in the SDK for an upcoming feature but currently throws NotImplementedError. on_call and offline are always set automatically.

To turn Do Not Disturb on or off for a user, update the user with your platform API key:

Bash

curl -X POST https://api.dialstack.ai/v1/users/USER_ID \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "DialStack-Account: ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"do_not_disturb": true}'