Phone
The connection, the lines, the devices, and the calls of the page.
Properties
Prop
Type
Methods
call(options)
Places a call and resolves with the Call as soon as it is created, before it rings.
Call it from a user action (a click): browsers only allow the microphone and sound after one.
The microphone and the speaker open first: if either fails, no call is placed. When the API could not dial (the line
went offline in between), the promise still resolves, with a call already ended: check call.state.
Prop
Type
Devices and volumes belong to the call and can change during it: see Call.
Rejects with a PhoneError:
| Code | When |
|---|---|
user_gesture_required | Not called from a user action, or the browser blocked the sound |
line_offline | The phone is not connected (state other than connected), or the line is offline |
invalid_request (param: 'lineId') | No lineId while the phone has several lines, or none |
microphone_denied, microphone_not_found | The microphone could not open; no call was placed |
speaker_not_found | The chosen output is unplugged or not allowed; no call was placed |
audio_unavailable | The page cannot run Web Audio |
line_busy, invalid_number, forbidden, other API codes | Refused by the API |
devices()
Resolves with { inputs: MediaDeviceInfo[]; outputs: MediaDeviceInfo[] }. Device labels are empty until the user has
granted microphone access once. outputs is empty where phone.canChooseOutput is false. Rejects with
audio_unavailable when the page has no access to media devices (insecure origin).
Use it to fill device pickers, then pass the chosen ids to call() or answer(). phone.canChooseOutput tells
whether the browser can pick a speaker, so you can hide that picker.
testMicrophone(options?)
Plays the microphone back half a second later, through the same processing as a call, so the user can check a device
and a volume before calling. Takes input, output, inputVolume and outputVolume like call(), with the same
defaults. Returns { stop(): void }, which releases the microphone. Call it from a user action: it rejects with
user_gesture_required otherwise, and with the microphone and speaker codes of call(); on failure the microphone is
released.
connect() / disconnect()
Open or close the WebRTC session. connect() while a reconnection is pending opens the session now, without opening
a second one. disconnect() hangs up the call in progress, ends any ringing call here, and stops refreshing the key.
Reconnection
The session is lost when ICE fails (the browser gives up on the network path) or its data channel closes. The phone
then goes reconnecting and opens a new session after a growing wait: 1 second plus a quarter of the time already
lost, at most 10 seconds between tries; when the browser comes back online it tries at once. After 2 minutes it gives
up: the state goes closed, an error event carries connection_lost, and calls end with line_offline.
A call does not survive the loss of its session: the API hangs it up, since its audio ran over that session. During
the reconnection the Call keeps its last state; once the new session is open, the phone asks the API for the real
state of its calls, which then end with the reason the API recorded. A brief network glitch that ICE recovers from on
its own does not lose the session.
Events
phone.on(event, handler) returns a function that removes the handler.
Prop
Type
Line is the object of the API, with camelCase keys. SMS are not in the SDK: they
reach your server through webhooks.