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

JavaScript

// Subscribe to all users in the account
phone.subscribePresence();

// Or subscribe to specific users
phone.subscribePresence(['user_01h2xcejqtf2nbrexx3vqjhp42', 'user_01h2xcejqtf2nbrexx3vqjhp43']);

// 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

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 of three values 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 carries dnd. This matches the REST presence API, which reports state and do_not_disturb independently.

Setting Your Status

JavaScript

// Set yourself as Do Not Disturb
await phone.setPresence('dnd');

// Set yourself as available
await phone.setPresence('available');

// Set with custom status text
await phone.setPresence('away', 'In a meeting until 3pm');

The on_call and offline statuses are managed automatically — you cannot set them manually.

REST API

You can also read and update your own presence via the REST API:

Bash

# Get current presence
curl https://api.dialstack.ai/v1/me/presence \
  -H "Authorization: Bearer USER_TOKEN"

# Update presence
curl -X PUT https://api.dialstack.ai/v1/me/presence \
  -H "Authorization: Bearer USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "dnd", "status_text": "In a meeting" }'