Skip to main content

@dialstack/sdk-dev / webrtc/src / DialStackPhone

Class: DialStackPhone

Defined in: sdk/webrtc/src/phone.ts:171

Constructors​

Constructor​

TypeScript
new DialStackPhone(options): DialStackPhone;

Defined in: sdk/webrtc/src/phone.ts:251

Parameters​

options​

PhoneOptions

Returns​

DialStackPhone

Properties​

activeCalls​

TypeScript
readonly activeCalls: Call[] = [];

Defined in: sdk/webrtc/src/phone.ts:173


isConnected​

TypeScript
isConnected: boolean = false;

Defined in: sdk/webrtc/src/phone.ts:172

Accessors​

audioInputDeviceId​

Get Signature​

TypeScript
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​

TypeScript
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​

TypeScript
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​

TypeScript
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()​

TypeScript
call(destination): Promise<Call>;

Defined in: sdk/webrtc/src/phone.ts:869

Parameters​

destination​

string

Returns​

Promise<Call>


clearEmergencyAddressRegisteredIp()​

TypeScript
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()​

TypeScript
connect(): Promise<void>;

Defined in: sdk/webrtc/src/phone.ts:437

Returns​

Promise<void>


deleteEmergencyAddress()​

TypeScript
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()​

TypeScript
disconnect(): void;

Defined in: sdk/webrtc/src/phone.ts:704

Returns​

void


getCall()​

TypeScript
getCall(callId): Call | undefined;

Defined in: sdk/webrtc/src/phone.ts:1091

Parameters​

callId​

string

Returns​

Call | undefined


getEmergencyAddress()​

TypeScript
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()​

TypeScript
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​

TypeScript
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​

TypeScript
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​

ListDirectoryOptions

Returns​

Promise<TypedDirectoryEntry[]>

Call Signature​

TypeScript
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?​

ListDirectoryOptions

Returns​

Promise< | DirectoryEntry[] | TypedDirectoryEntry[]>


listEmergencyAddresses()​

TypeScript
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()​

TypeScript
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()​

TypeScript
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()​

TypeScript
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()​

TypeScript
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()​

TypeScript
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()​

TypeScript
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()​

TypeScript
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()​

TypeScript
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()​

TypeScript
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()​

TypeScript
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​

EmergencyAddressInput

Returns​

Promise<EmergencyAddress>


setPresence()​

TypeScript
setPresence(_status, _statusText?): Promise<void>;

Defined in: sdk/webrtc/src/phone.ts:1134

Parameters​

_status​

SettablePresenceStatus

_statusText?​

string

Returns​

Promise<void>


setToken()​

TypeScript
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()​

TypeScript
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