Live calling

By arrangement with Trellus

What live calling needs

Anyone can install the packages and build against the mock transport. Placing a real call needs all of the following:

• A Trellus account.
• A rep API key. Your application supplies it through getApiKey.
• The Twilio Voice SDK, @twilio/voice-sdk version >=2.18.0 <3, installed alongside the SDK.
• Enablement by Trellus. A line setting in code does not grant entitlement.

Talk to Trellus about live access. Already have a Trellus account? Contact Trellus support.

createBrowserDialer

The browser entry point is the smallest live integration. createBrowserDialer imports the Twilio Voice SDK lazily and wires the headless SDK to the live transport.

import { createBrowserDialer } from '@trellusrelease/dialer-sdk/browser';

const dialer = await createBrowserDialer({ getApiKey: getAuthenticatedRepTrellusKey, maxLines: 3 });
// A user action starts registration; creating the object has no calling side effects.
await dialer.connect();

getAuthenticatedRepTrellusKey is yours to implement. The package does not supply it.

• Creating the dialer has no calling side effects. It does not request a credential or register a device until connect().
• connect() requests microphone access and prepares input audio. Call it from a real user action so the browser can activate audio.
• Each instance registers under its own generated suffix. That keeps audio routing separate. It does not lock queue ownership across tabs.

createTrellusTransport

Build the transport yourself when you want to pass your own Twilio Device import or keep the transport and the dialer separate. Set maxLines on both.

import { Device } from '@twilio/voice-sdk';
import { createDialer } from '@trellusrelease/dialer-sdk';
import { createTrellusTransport } from '@trellusrelease/dialer-sdk/transport';

const transport = createTrellusTransport({
  Device,
  getApiKey: async () => getAuthenticatedRepTrellusKey(),
  platform: 'TRELLUS_DIALER',
  maxLines: 3,
  deviceSuffix: `sdk-${crypto.randomUUID()}`,
});

const dialer = createDialer({
  transport,
  maxLines: 3,
  onDisposition: async ({ call, disposition }) => {
    // Your authenticated application persists the exact task/attempt outcome.
    // Resolve only when your own save contract succeeds.
    await saveCallOutcome({
      taskId: call.taskId,
      attemptId: call.attemptId,
      sessionId: call.sessionId,
      ...disposition,
    });
  },
});

// Invoke from a genuine user action so browser audio can activate.
await dialer.connect();
await dialer.dial({ id: 'task-1', name: 'Alex Example', phoneNumber: '+12025550123' });

getAuthenticatedRepTrellusKey and saveCallOutcome are yours to implement. They are not endpoints supplied by the package.

The transport is a browser adapter. It needs no extension, DOM interface or Chrome APIs. It reports its line cap to the dialer when it connects.

In this preview the transport delivers call status, transcripts and detection values. It does not deliver call summaries. Integrate durable final call data separately, through a reporting or webhook path agreed with Trellus.

The Twilio Voice SDK

Live audio runs through the Twilio Voice SDK in the rep’s browser. Install @twilio/voice-sdk, version >=2.18.0 <3, alongside the SDK.

npm install @trellusrelease/dialer-sdk @twilio/voice-sdk

• The packages do not bundle Twilio. It is an optional peer dependency.
• createBrowserDialer imports it lazily. Pass Device to reuse an import your application already owns.
• createTrellusTransport takes the Device constructor as a required option.
• If the dialer runs inside an iframe, the iframe must permit microphone use.
• The mock transport does not contact Twilio.

Credentials

The SDK authenticates as one rep. Your application supplies that rep’s Trellus API key through getApiKey.

• Supply the key through getApiKey only. It is your function. createBrowserDialer rejects raw credential options, and transportOptions accepts none.
• Keep the key in memory. The transport never persists it.
• Keep the key out of URLs, task metadata, logs and telemetry. Public snapshots, session views and event payloads never contain API keys, device tokens or transport session handles.
• One active dialer per rep. A distinct device registration avoids identity collisions. It does not authorize concurrent dialers for one rep, and the SDK has no cross-tab ownership lease. Your application coordinates one active owner per rep.
• Do not surface provider errors. Audio and device controls can reject with errors from the audio provider. Do not show those messages to users or write them to telemetry. Use the sanitized SDK code and message.

Review credential handling with Trellus before you put a rep key in a browser application.

Line limits

• The headless core accepts maxLines from 1 to 10. The default is 1.
• The supplied Trellus transport and createBrowserDialer accept 1 to 4.
• The effective limit is the smaller of the dialer’s setting and the cap the transport reports. Read it from snapshot.maxLines.
• A line setting in code does not grant entitlement.
• The preview does not fetch a team’s or a rep’s dialing settings, and it does not authorize a requested line count. Confirm the line count with Trellus before you set it.

Custom transports

The headless SDK talks to any object that implements DialerTransport. Use the supplied Trellus transport for live calling and the mock transport for local work. Implement the interface yourself only for a server-mediated integration agreed with Trellus.

interface TransportSession { readonly id: string }

interface DialerTransport<Session extends TransportSession = TransportSession> {
  connect(): Promise<void | { maxLines?: number }>;
  prepare?(options: { mode: DialMode; lines: number }): Promise<void>;
  createCall(options: {
    attemptId: string;
    task: DialTask;
    mode: DialMode;
    lines: number;
    canStartCall: () => boolean;
  }): Promise<Session>;
  subscribe(session: Session, listener: (event: TransportEvent) => void): (() => void) | void;
  hangup(session: Session): Promise<void>;
  mute?(session: Session, muted: boolean): Promise<void>;
  sendDigits?(session: Session, digits: string): Promise<void>;
  getAudioDevices?(): Promise<AudioDevices>;
  setInputDevice?(id: string): Promise<void>;
  setOutputDevice?(id: string): Promise<void>;
  dispose(): void | Promise<void>;
}

A transport reports what happens to a call with this small set of events:

{ type: 'ringing' }
{ type: 'connected' } // Rep actually bridged; not merely destination answered.
{ type: 'ended' }
{ type: 'transcript', segments: TransportTranscriptSegment[] }
{ type: 'detection', value: string }
{ type: 'summary', text: string }
{ type: 'error', error?: { code?: string, outcomeUnknown?: boolean } }

Rules a transport must follow

• Each session handle needs a stable, nonempty id of at most 256 characters. The SDK keeps the handle private. Only the id is exposed, as sessionId.
• Check canStartCall() immediately before dispatch, after any asynchronous preparation. A cancellation before dispatch must not place a call.
• If a create may have been dispatched but its result is uncertain, reject with outcomeUnknown: true.
• Emit connected only with evidence that this rep joined this exact session. A destination that answers is not enough.
• Correlate every event to its exact handle, and keep events that arrive before subscribe is called.
• Never report a lost event stream as ended.
• A transcript event supplies the current segment set, not an append instruction. Final transcript updates may arrive after ended.
• Set isFinal: true on a segment only when finality is confirmed. When it is omitted, the public output shows false.
• Reject unsupported features explicitly instead of pretending success.

When a transport returns an invalid or reused session ID, the SDK treats the result as uncertain. It keeps the capacity as unknown, emits no session.created and does not subscribe to that handle. See uncertain outcomes.