@dialstack/sdk-dev / webrtc/src / DialStackPhone
Class: DialStackPhone
Defined in: sdk/webrtc/src/phone.ts:156
Constructors
Constructor
new DialStackPhone(options): DialStackPhone;
Defined in: sdk/webrtc/src/phone.ts:215
Parameters
options
Returns
DialStackPhone
Properties
activeCalls
readonly activeCalls: Call[] = [];
Defined in: sdk/webrtc/src/phone.ts:158
isConnected
isConnected: boolean = false;
Defined in: sdk/webrtc/src/phone.ts:157
Accessors
audioInputDeviceId
Get Signature
get audioInputDeviceId(): string | null;
Defined in: sdk/webrtc/src/phone.ts:236
The microphone deviceId new calls capture, or null for the OS default.
Returns
string | null
audioOutputDeviceId
Get Signature
get audioOutputDeviceId(): string | null;
Defined in: sdk/webrtc/src/phone.ts:241
The speaker deviceId the ringback plays through, or null for the OS default.
Returns
string | null
isConnecting
Get Signature
get isConnecting(): boolean;
Defined in: sdk/webrtc/src/phone.ts:164
A connect() is in flight but not yet connected. Consult alongside
isConnected — connect() throws on a concurrent call.
Returns
boolean
presentedEmergencyAddressId
Get Signature
get presentedEmergencyAddressId(): string | null;
Defined in: sdk/webrtc/src/phone.ts:794
The emergency-address id actually sent in the CURRENT socket's authenticate
frame (latched at send time), or null. This is what the E911 gate keys off —
a saved address's registered_ip, or a selection made without a reconnect,
does NOT mean this session bound it.
Returns
string | null
Methods
call()
call(destination): Promise<Call>;
Defined in: sdk/webrtc/src/phone.ts:577
Parameters
destination
string
Returns
Promise<Call>
clearEmergencyAddressRegisteredIp()
clearEmergencyAddressRegisteredIp(id): Promise<void>;
Defined in: sdk/webrtc/src/phone.ts:859
Clear an address's network binding (registered_ip) via the REST API. The next connect re-registers the current network. Useful after a move so the address re-binds where the device now is.
Parameters
id
string
Returns
Promise<void>
connect()
connect(): Promise<void>;
Defined in: sdk/webrtc/src/phone.ts:396
Returns
Promise<void>
deleteEmergencyAddress()
deleteEmergencyAddress(id): Promise<void>;
Defined in: sdk/webrtc/src/phone.ts:846
Delete a saved emergency address. Clears the local selection if it matched.
Parameters
id
string
Returns
Promise<void>
disconnect()
disconnect(): void;
Defined in: sdk/webrtc/src/phone.ts:505
Returns
void
getCall()
getCall(callId): Call | undefined;
Defined in: sdk/webrtc/src/phone.ts:709
Parameters
callId
string
Returns
Call | undefined
getEmergencyAddress()
getEmergencyAddress(id?): Promise<EmergencyAddress>;
Defined in: sdk/webrtc/src/phone.ts:799
Fetch a saved emergency address (defaults to the one this phone uses).
Parameters
id?
string
Returns
Promise<EmergencyAddress>
listAudioDevices()
listAudioDevices(): Promise<AudioDeviceList>;
Defined in: sdk/webrtc/src/phone.ts:334
The available audio devices. Deliberately does not prompt for mic access — opening
a picker shouldn't spring a permission dialog — so names stay hidden until
permission has been granted once (labelsAvailable: false).
Returns
Promise<AudioDeviceList>
listDirectory()
listDirectory(): Promise<DirectoryEntry[]>;
Defined in: sdk/webrtc/src/phone.ts:835
List the account directory — the colleagues this user may see, by name
(GET /v1/me/directory). Resolved from the session token alone (no account
context needed), so a softphone can discover who to watch for presence, or
populate a contact / transfer picker, without its backend supplying the set.
Auto-paginates the whole directory and returns a flat list. To watch every
colleague's presence: phone.subscribePresence((await phone.listDirectory()).map(e => e.user)).
Note presence subscription accepts at most 100 users at once, so watching a
very large directory means subscribing to a subset.
Returns
Promise<DirectoryEntry[]>
listEmergencyAddresses()
listEmergencyAddresses(): PaginatedList<ListResponse<EmergencyAddress>>;
Defined in: sdk/webrtc/src/phone.ts:819
List the user's saved emergency addresses (location profiles).
Auto-paginating: await it for the first page envelope, or iterate the
full collection with autoPagingEach() / autoPagingToArray() —
subsequent pages are fetched lazily.
Returns
PaginatedList<ListResponse<EmergencyAddress>>
off()
off<K>(event, handler?): void;
Defined in: sdk/webrtc/src/phone.ts:366
Type Parameters
K
K extends keyof PhoneEventMap
Parameters
event
K
handler?
Listener<K>
Returns
void
on()
on<K>(event, handler): void;
Defined in: sdk/webrtc/src/phone.ts:356
Type Parameters
K
K extends keyof PhoneEventMap
Parameters
event
K
handler
Listener<K>
Returns
void
reconnect()
reconnect(): Promise<void>;
Defined in: sdk/webrtc/src/phone.ts:545
Tear down and reconnect, re-running the authenticate handshake. The new
session presents the current emergencyAddressId, which is where the server
binds the emergency address to the connection's network — so this is how an
app applies a just-selected/created address (or re-binds after a network
move). Safe to call while idle; any live calls are torn down.
Returns
Promise<void>
reconnectWithEmergency()
reconnectWithEmergency(emergencyAddressId): Promise<void>;
Defined in: sdk/webrtc/src/phone.ts:572
Re-present a chosen emergencyAddressId on a fresh authenticate handshake, in
one call. Rebinding requires a fresh socket (the server binds E911 once per
connection, after REGISTER), so this tears down and reconnects like
reconnect(); resolves once the server confirms the new binding.
Parameters
emergencyAddressId
string
Returns
Promise<void>
seedAudioInputDevice()
seedAudioInputDevice(deviceId): void;
Defined in: sdk/webrtc/src/phone.ts:252
Record a microphone preference WITHOUT acquiring it — for a host restoring a saved
selection at construction time. setAudioInputDevice probes the device, which
prompts for permission when no call is up; this doesn't, so a returning user isn't
asked for the mic on page load. An id that no longer resolves falls back to the
default at the next call's acquisition.
Parameters
deviceId
string | null
Returns
void
selectEmergencyAddress()
selectEmergencyAddress(id): void;
Defined in: sdk/webrtc/src/phone.ts:783
Select an already-saved emergency address to present on the next
(re)connect (sets + persists it). The server binds it at the authenticate
handshake, so call reconnect() afterwards for it to take effect.
Parameters
id
string
Returns
void
setAudioInputDevice()
setAudioInputDevice(deviceId): Promise<void>;
Defined in: sdk/webrtc/src/phone.ts:264
Select the microphone: seeds future calls and live-switches calls already up. Held
for this phone's lifetime only — saving the choice across sessions is the host's
(the React softphone does it). Rejects without recording the id when the device
can't be acquired. A single live call's failure surfaces on error rather than
rejecting, so one bad call can't leave the others behind.
Parameters
deviceId
string | null
Returns
Promise<void>
setAudioOutputDevice()
setAudioOutputDevice(deviceId): void;
Defined in: sdk/webrtc/src/phone.ts:321
Select the speaker for the ringback tone. Does NOT route remote call audio — that
plays through a media element the host owns, and only its owner can call
setSinkId. Void-returning because nothing here is verified or awaited.
Parameters
deviceId
string | null
Returns
void
setEmergencyAddress()
setEmergencyAddress(address): Promise<EmergencyAddress>;
Defined in: sdk/webrtc/src/phone.ts:767
Register and validate an emergency (E911) address. Creates the
resource via the REST API (validated against the carrier MSAG), persists
its id, and presents it on the next connect so the server binds it to the
device's network. This does not alter an already-authenticated session. To
apply a new address there (e.g. responding to a network.changed event),
pass the returned id to reconnectWithEmergency().
Rejects with a PhoneError (code invalid_message) when the address
can't be validated.
Parameters
address
Returns
Promise<EmergencyAddress>
setPresence()
setPresence(_status, _statusText?): Promise<void>;
Defined in: sdk/webrtc/src/phone.ts:752
Parameters
_status
_statusText?
string
Returns
Promise<void>
setToken()
setToken(token): void;
Defined in: sdk/webrtc/src/phone.ts:879
Replace the token for the NEXT connect, off the connected path — for a host
that mints its own tokens and must (re)connect with a fresh one (boot,
push-wake), which onTokenExpiring (live-session only) can't cover. Refuses
while connected/connecting: swapping there would desync the local token from
the one the server enforces and the session would die silently at expiry — to
swap a live session's token, disconnect() then setToken() before connect().
Parameters
token
string
Returns
void
subscribePresence()
subscribePresence(userIds): void;
Defined in: sdk/webrtc/src/phone.ts:733
Subscribe to presence (BLF) for an explicit, bounded set of users. The
watch set is required and non-empty — there is no whole-account default —
and is capped at MAX_PRESENCE_TARGETS; both bounds mirror the
server, which rejects a bad list with a non-fatal invalid_message error.
The server replies with a presence.list snapshot (emitted as
presenceList), always before any presence.update delta
(presenceUpdate) for the users that snapshot introduces. Deltas follow as
those users' status changes.
A status is available, on_call, or offline — offline meaning the user
has no registered device and so cannot currently receive calls. The first
delta after a snapshot may restate a status the snapshot already reported, so
key the roster by userId and upsert.
Users whose subscription can't be established are omitted from the snapshot
and named in a non-fatal presence_unavailable error (its PhoneError
carries no user list; listen on error for the code).
Parameters
userIds
string[]
Returns
void