@dialstack/sdk-dev / webrtc/src / DialStackPhone
Class: DialStackPhone
Defined in: sdk/webrtc/src/phone.ts:171
Constructors
Constructor
new DialStackPhone(options): DialStackPhone;
Defined in: sdk/webrtc/src/phone.ts:251
Parameters
options
Returns
DialStackPhone
Properties
activeCalls
readonly activeCalls: Call[] = [];
Defined in: sdk/webrtc/src/phone.ts:173
isConnected
isConnected: boolean = false;
Defined in: sdk/webrtc/src/phone.ts:172
Accessors
audioInputDeviceId
Get Signature
get audioInputDeviceId(): string | null;
Defined in: sdk/webrtc/src/phone.ts:277
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:282
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:179
A connect() is in flight but not yet connected. Consult alongside
isConnected; a concurrent connect() joins the one in flight.
Returns
boolean
presentedEmergencyAddressId
Get Signature
get presentedEmergencyAddressId(): string | null;
Defined in: sdk/webrtc/src/phone.ts:1177
The emergency-address id the server last evaluated for the CURRENT
connection, or null: the one sent in its authenticate frame (latched at send
time), or the last one rebindEmergencyAddress() got an answer for. This is
what the E911 gate keys off — a saved address's registered_ip, or a
selection never sent to the server, does NOT mean this session bound it.
Returns
string | null
Methods
call()
call(destination): Promise<Call>;
Defined in: sdk/webrtc/src/phone.ts:869
Parameters
destination
string
Returns
Promise<Call>
clearEmergencyAddressRegisteredIp()
clearEmergencyAddressRegisteredIp(id): Promise<void>;
Defined in: sdk/webrtc/src/phone.ts:1266
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:437
Returns
Promise<void>
deleteEmergencyAddress()
deleteEmergencyAddress(id): Promise<void>;
Defined in: sdk/webrtc/src/phone.ts:1253
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:704
Returns
void
getCall()
getCall(callId): Call | undefined;
Defined in: sdk/webrtc/src/phone.ts:1091
Parameters
callId
string
Returns
Call | undefined
getEmergencyAddress()
getEmergencyAddress(id?): Promise<EmergencyAddress>;
Defined in: sdk/webrtc/src/phone.ts:1182
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:375
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()
Call Signature
listDirectory(): Promise<DirectoryEntry[]>;
Defined in: sdk/webrtc/src/phone.ts:1218
List the account directory — the other users in this user's account, by name and
extension number (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
user'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[]>
Call Signature
listDirectory(options): Promise<TypedDirectoryEntry[]>;
Defined in: sdk/webrtc/src/phone.ts:1225
List the directory entries of the given types — users and the account's
other dialable destinations (queues, ring groups, voice apps, dial plans,
shared voicemail boxes), e.g. for a transfer picker. Each entry's id
identifies it whatever its type.
Parameters
options
Returns
Promise<TypedDirectoryEntry[]>
Call Signature
listDirectory(options?): Promise<
| DirectoryEntry[]
| TypedDirectoryEntry[]>;
Defined in: sdk/webrtc/src/phone.ts:1226
List the account directory — the other users in this user's account, by name and
extension number (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
user'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.
Parameters
options?
Returns
Promise<
| DirectoryEntry[]
| TypedDirectoryEntry[]>
listEmergencyAddresses()
listEmergencyAddresses(): PaginatedList<ListResponse<EmergencyAddress>>;
Defined in: sdk/webrtc/src/phone.ts:1202
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:407
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:397
Type Parameters
K
K extends keyof PhoneEventMap
Parameters
event
K
handler
Listener<K>
Returns
void
rebindEmergencyAddress()
rebindEmergencyAddress(emergencyAddressId, options?): Promise<{
bound: boolean;
}>;
Defined in: sdk/webrtc/src/phone.ts:803
Bind an emergency address to this connection's network without reconnecting, so calls in progress stay up.
Without anchor, the server checks the address against the network it was
confirmed on, as it does when the phone connects: an address confirmed on
another network is not bound. Pass anchor: true when the user has just
confirmed they are at this address, or has just created it: the address is
then confirmed for the current network, whatever network it was confirmed on
before.
Resolves with bound: false when the server could not bind the address on
this network; network.changed is emitted first in that case. When the phone
is not connected, it connects (or waits for the reconnect in progress) and
then binds. Rejects with transport_closed if the connection drops first.
Parameters
emergencyAddressId
string
options?
anchor?
boolean
Returns
Promise<{
bound: boolean;
}>
reconnect()
reconnect(): Promise<void>;
Defined in: sdk/webrtc/src/phone.ts:751
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:782
Re-present a chosen emergencyAddressId on a fresh authenticate handshake, in
one call. This tears down and reconnects like reconnect(), ending any live
calls; resolves once the new session is authenticated.
Parameters
emergencyAddressId
string
Returns
Promise<void>
Deprecated
Use rebindEmergencyAddress(), which binds the address on the
open connection and keeps calls up. Removed in the next major version.
seedAudioInputDevice()
seedAudioInputDevice(deviceId): void;
Defined in: sdk/webrtc/src/phone.ts:293
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:1165
Select an already-saved emergency address to present on the next
(re)connect (sets + persists it). It does not bind the address to the open
connection; use rebindEmergencyAddress() for that.
Parameters
id
string
Returns
void
setAudioInputDevice()
setAudioInputDevice(deviceId): Promise<void>;
Defined in: sdk/webrtc/src/phone.ts:305
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:362
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:1149
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. It does not bind the address to an already-authenticated
session. To apply it there (e.g. responding to a network.changed event),
pass the returned id to rebindEmergencyAddress(), which keeps calls up.
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:1134
Parameters
_status
_statusText?
string
Returns
Promise<void>
setToken()
setToken(token): void;
Defined in: sdk/webrtc/src/phone.ts:1286
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:1115
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