@robono/calling
v0.7.0
Published
WebRTC voice, video, group calling and screen sharing within apps and across Robono Bridge networks.
Readme
Robono Calling SDK
Add voice and video calls within your app or between people connected across Robono Bridge networks, with optional group calls and screen sharing. The SDK manages WebRTC negotiation, direct connections, relay fallback, call state and microphone cleanup. Your app keeps its identity and platform notification integration. Use your own interface, or choose the separate optional mobile screen package. The calling engine never requires a Robono interface.
See how calling connects for hosted responsibilities, direct/relay paths, phone credentials and the supported calling boundaries. Live-call recording/captions and large conferences are not implied by voice-message transcription or messaging supergroups.
Start here
For calls in the supplied Messenger, follow the hosted setup guide. Select voice and/or video in Features & preview, then run the Robono installer in your app. The supplied Messenger connects calling automatically. Native apps also need your Apple/Google notification credentials and a native rebuild, as described in the generated setup guide.
The reference below is for custom calling interfaces and advanced connections. You do not need to implement admission, signaling or call controllers yourself when using the supplied Messenger.
Advanced: install the calling engine
npm install @robono/callingThis is a versioned npm-compatible package. Commit your package lockfile to retain its integrity checksum. The release includes SHA256SUMS and the package includes an SPDX software bill of materials.
Connect your backend
Select calling in Features & preview. For a custom connection, copy the integration’s admission and service URLs from its calling setup. Your server authenticates the user, then posts the following to that URL using a network API key with calling:connect scope:
{"operation":"admit","kind":"network","protocolVersion":1,"externalUserId":"YOUR_AUTHENTICATED_USER_ID"}Use the exact external user ID from the accepted Bridge relationship. Validate the returned serviceUrl against your configured calling service, then exchange the returned ticket within 60 seconds at serviceUrl + '/sessions' using {ticket, connectionId}. A connection ID is bridge:CONNECTION_ID between networks or app:CONVERSATION_ID for a Robono Messenger endpoint. Omit connectionId to listen across authorized contacts.
Return the service URL, resulting session token and expiry to that user's client over HTTPS. Keep network API keys on your server and tokens out of logs and URLs. Renew expired sessions through your authenticated backend; never silently reopen a microphone.
Both networks must allow voice on the accepted relationship:
{"calling":{"voice":true,"video":false,"protocol_version":1}}Keep the existing messaging capabilities and protocol version. Check live availability before enabling a call action.
Browser integration
Create one client per signed-in device and keep it alive across screen navigation. Here session comes from your backend, audio is an HTML audio element, and renderCall updates your app's UI:
import { RobonoCallingClient, createHttpTransport } from '@robono/calling';
const client = new RobonoCallingClient({
request: createHttpTransport({ baseUrl: session.serviceUrl, token: session.token }),
onChange: renderCall,
onRemoteStream(stream) {
audio.srcObject = stream;
if (stream) audio.play().catch(() => showEnableAudioButton());
}
});
await client.listen();
const { voiceAvailable } = await client.availability(connectionId);
// Bind these to user actions, with error handling in your UI:
// await client.call(connectionId);
// await client.answer();
// client.mute(true); client.mute(false);
// await client.hangUp();
// await client.dispose(); // logout or destruction of this device sessionUse HTTPS and request microphone permission from the Call or Answer action. Browsers may require a user gesture to play remote audio. Do not call answer() just because a notification arrived. forceRelay: true is available for your relay acceptance test; normal calls prefer a direct route.
Use the onChange snapshot to render ringing, connecting and connected states. Start the timer at call.connectedAt, not when Answer is pressed. A preparation state can precede a server call ID; retain the same screen and allow cancellation. hangUp() handles cancellation, decline and ending an active call.
Optional mobile interface
@robono/calling-react-native is a separate package for networks that want supplied React Native screens, sounds, controls and audio adapters. It is not a dependency of this engine. Existing WebRTC clients and networks with their own calling UI can continue using the engine or HTTP API without installing it.
Native hosts
Supply getUserMedia, createPeerConnection and, if needed, createRemoteStream adapters through the constructor. The microphone adapter receives an optional {isCurrent} callback: check it before capture after asynchronous permission or audio-session work. A late returned stream is stopped if the call has already been cancelled.
The headless SDK does not install iOS or Android native code. Your host manages microphone permission, audio sessions/focus, speaker/Bluetooth routing, interruptions, background execution, native incoming UI and push delivery. Select the speaker route before connection if requested and preserve it when media starts. Release native audio resources when the call ends. Use the same protocol on both platforms.
Incoming notifications
Enable network notifications on your admission endpoint with {"operation":"notifications","enabled":true}. Robono sends signed calling.incoming and calling.dismissed events to your network webhook. Your backend sends push through your app's own provider; Robono does not receive your app's push keys through this SDK.
Use the matching backend release:
npm install https://github.com/IMLX16/robono-sdks/releases/download/calling-v0.1.1/robono-server-0.11.0.tgzVerify the raw webhook body with verifyRobonoWebhook, then use toCallingPushPayload from @robono/server. Route only to devices owned by recipient.external_user_id in recipient.child_app_id. Durably queue verified events before acknowledging them. Deduplicate by event_id; retain the highest per-call sequence for at least 24 hours. A dismissal (sequence 2) overrides an invitation (sequence 1), even if events arrive out of order. Never ring past ring_expires_at. Dismissal clears ringing; it does not end an answered call.
When opened, a notification should authenticate the current user and refresh current call state. Notification content is routing information, not authorization. Platform settings control notification presentation and delivery.
History
import { mergeCallHistory, describeCall } from '@robono/calling/history';
const page = await client.history({ after: saved.cursor, limit: 100 });
const updated = mergeCallHistory(saved, page);
await saveHistory(updated); // Commit entries and cursor together.
const label = describeCall(updated.entries.at(-1));Initialize saved as {cursor: 0, entries: []}. Continue while hasMore is true. Keep separate history cursors per account and query scope. Store entries by call ID and show them on the caller's side of the conversation. durationMs excludes ringing and setup. Refresh history on resume and hangup, and recheck availability before callback.
Failure handling
- 401: stop media and obtain a new session through your backend.
- 403: refresh account and relationship permissions.
- 409: refresh call state; another device may control the call or a participant may be busy.
- 429: back off before retrying.
- 503/network failure: use bounded retries and show a recoverable error.
The client retries ambiguous Start responses with the same request ID, stops late microphone capture after cancellation, and releases media on signaling loss. Your UI should handle rejected actions and avoid automatic redial.
Verify your integration
Use two sandbox networks and two devices. Check calls both ways, audible two-way speech, mute, speaker, Bluetooth, decline, caller cancellation, no answer, history, Wi-Fi/cellular and relay fallback. Repeat native foreground, background and locked-screen tests on iPhone and Android. Confirm messaging continues working during rollout.
The package uses ESM and includes TypeScript declarations. Node.js 22+ runs its development tests; browser/native hosts provide WebRTC.
License and support
Use is governed by the included Robono SDK License Agreement. Contact Robono support.
Ringing and interruptions
Unanswered calls expire 30 seconds after creation. Stop ringing at ringRemainingMs (a duration from the response), or ringExpiresAt for older responses. A late Answer is rejected. Do not send End to represent a timeout: that action means user cancellation or decline. The service records no_answer independently, and the client also stops a stale ringing screen when polling stalls.
For an established call, client.hold() silences local and remote tracks immediately and acknowledges the interruption to the service. A held endpoint can stop polling for up to five minutes; retries do not extend that deadline. The other endpoint keeps its normal signaling lease and may hang up. Show Call on hold when localHeld or remoteHeld is true. Keep the user's manual mute preference separate from hold.
Call client.resume(prepareAudio) only when the OS permits audio to return, or when the person explicitly requests resume. The client first refreshes authorization and call state, then awaits your prepareAudio callback, acknowledges resume and restores tracks. The callback must reject if another call still owns audio. A stale response, remote hangup, expired session or ended call cannot restart capture. The optional mobile package supplies this wiring and a Resume call control. No voicemail is involved.
Optional video
Check availability(connectionId).videoAvailable separately from voiceAvailable. Start a video call with client.call(connectionId, {kind: 'video'}). Ordinary client.call(connectionId) remains voice-only. The host's media adapter receives {kind, isCurrent}; a video call requires one audio track and one video track. Use onLocalStream and onRemoteStream to render previews, setCamera(enabled) to control outgoing video, and setVideoForeground(active) when application visibility changes. Disposal stops all captured tracks.
Both apps and the relationship must allow video. Voice-only sessions do not receive video invitations. When using your own WebRTC client, send mediaKinds: ['voice', 'video'] with /state, kind: 'video' with /ice and /start, and supply one audio and one video SDP media section. Voice requests omit kind or use voice. No data channel or additional camera tracks are admitted. Media travels directly when possible, using the configured relay fallback when needed.
Final call history includes kind; older records without it are voice calls. Usage records distinguish voice and video and retain connection duration, not the media itself.
Usage protection and operational visibility
The service applies the same protections to own-network and cross-network calls.
Preserve the request ID when retrying a lost call-start response. Honor
Retry-After; a deliberate new call needs a new request ID. Call status and
hangup have separate limits so a start loop does not block cleanup.
The SDK sends bounded, best-effort transport byte counters every fifteen seconds while connected. They contain no audio, video, transcripts, IP addresses or ICE candidates. Counters are approximate and are not used to calculate charges.
Use the Server SDK from your backend for monitoring() and revision-numbered
setUserPermissions(). See limits, costs and alerts.
Event-based listening
Use @robono/[email protected] with @robono/[email protected] when using the optional mobile interface. Existing custom interfaces remain supported. See https://robono.com/docs#calling-events for the lifecycle and recovery contract.
- Foreground, idle: an authenticated WebSocket listens for incoming calls. No periodic state polling. A ping/pong every 20 seconds maintains presence.
- Active calls: events trigger state reconciliation immediately; a state health check runs every 3 seconds. The optional native runtime also provides a three-second background recovery check when device timers are suspended; simultaneous refreshes share one request.
- Idle in background: call
setForeground(false). The event socket and state checks stop. Your backend delivers Robono's signed incoming-call events through your app's APNs/FCM notifications. A WebSocket does not replace push delivery. - Return to foreground: call
setForeground(true). The socket reconnects and current state is checked. Do not create a new call to recover a listening session. The optional controller forwards this lifecycle method to the engine. - Event reconnection: delays start at 1 second, double to 30 seconds (plus up to 20% jitter), honor Retry-After, and continue at a bounded 60-second interval after eight failures. Successful reconnect immediately reconciles current calls, including invitations missed during the outage. Authentication failures stop recovery and require a fresh authorized session.
- Expired idle sessions:
onSessionExpiredrequests new admission without presenting a failed-call screen. Dispose the expired client and create a new one with a new session from your backend. Use bounded backoff for admission failures. Authorization revocation is not a retryable session expiration. An active call cannot be transferred to a new session.
createHttpTransport supplies the event subscription automatically. If wrapping it, preserve request.subscribe = transport.subscribe. A custom request without subscribe, or {events:false}, uses a five-second idle fallback; active calls without event support use pollMs (default 1000 ms). Event-enabled active calls use a three-second health check. While event transport is unavailable, the five-second idle fallback runs until events reconnect.
The 0.1.2 engine had polling and retry backoff but did not include this event transport. No native permissions or rebuild are added by this JavaScript patch to an app already using the native calling package.
Connection details
Direct and group clients expose getDiagnostics() for local connection measurements without addresses, media or credentials. The supplied call overlays include an optional Connection details panel; custom interfaces can use the same measurements. Guide, fields and customization. Missing measurements remain unknown, and the first sample cannot calculate interval rates.
Recording, captions and local call tools
Robono hosts optional call recording and transcription. Enable recording once in the existing Calling settings; every participant must agree before capture, and anyone can stop it. The supplied controls include the consent notice, active-recording status and captions. No customer recording server is required.
The supplied adapters also offer camera/microphone/speaker checks and camera background blur. Screen sharing is separate. Phone blur requires rebuilding the native app; browser blur downloads its model only when selected and needs the documented content-security policy. Background processing stays on the device.
See the recording and call tools guide for prices, retention, short-lived downloads, deletion, platform requirements and label customization. Captions arrive in short batches with several seconds of delay and can be inaccurate; incomplete transcripts are marked.
Event credential compatibility (0.6.3)
createHttpTransport({baseUrl: session.serviceUrl, token: session.token,
eventsToken: session.eventsToken}) keeps the control credential on HTTP requests
and uses the separate credential for event hints. Hint credentials cannot read or
control calls. If an older server adapter omits eventsToken, the corrected client
exchanges the existing valid HTTP session once at /events-session; it reuses that
credential on reconnect. This endpoint requires the corresponding service update.
An older service returning 404 retains the legacy path; it does not bypass its
origin restrictions. HTTP 401/403 still requires renewal/revocation handling.
Server 0.14.0's calling module omits eventsToken. Replace the vendored calling
module with the supported RobonoCallingBackend export from @robono/server
and return createSession()'s full response. Identity, API keys, setRelationship
and per-friend permission checks stay on the customer's server. Newer existing
server packages already preserve this field; calling 0.6.3 adds the direct-client correction and
legacy exchange above. The supplied Messenger's encrypted
handle transport already uses the separate event credential.
