Dialer SDK API reference

The public surface of the headless SDK: createDialer, the task shape, every dialer method, the snapshot, and errors. The package’s TypeScript declarations are the authority.

View as Markdown

@trellusrelease/dialer-sdk

Create a dialer

createDialer is the root export. It takes a transport and returns a Dialer. Call connect() to register and prepare the transport before you dial.

createDialer

createDialer({
  transport,
  maxLines?: number,       // Default 1; integer 1–10.
  onDisposition?: async ({ call, disposition }) => void,
  createId?: () => string, // Unique per attempted destination call.
})

createDialer options
Option	Type and meaning
`transport` Required	`DialerTransport` The transport that places calls: the supplied Trellus transport, the mock transport, or your own.
`maxLines` Optional	`number` Client line ceiling. An integer from 1 to 10. Default 1. The effective ceiling is the smaller of this value and the ceiling the transport reports. It does not grant entitlement.
`onDisposition` Optional	`(result: { call: DialCall; disposition: Disposition }) => void \| Promise<void>` Your save hook. `completeWrapUp` awaits it before it clears wrap-up.
`createId` Optional	`() => string` Returns an ID that is unique for each attempted destination call.

The effective line ceiling is the smaller of your maxLines and the ceiling the transport reports. A client ceiling is not a server entitlement.

Task shape

A task is one contact to call. Manual, power and parallel modes all use the same shape.

DialTask

{
  id: string;
  phoneNumber: string; // E.164, e.g. +12025550123.
  name?: string;
  metadata?: Record<string, unknown>; // Structured-cloneable application metadata.
}

Task IDs must be nonempty and unique within a queue.
setTasks accepts up to 10,000 tasks and keeps their input order.
metadata is your own context. It is passed to the transport and left out of public task snapshots.
Keep credentials out of metadata. Whether a custom transport sends metadata to a server is part of that transport’s contract.

Methods

These are the methods of the Dialer interface. Controls such as hangup() take the SDK attemptId. Session lookup takes the Trellus sessionId.

Dialer methods
Method	Behavior
`getSnapshot()` Returns `DialerSnapshot`	Returns the current state, detached. Editing it cannot change the dialer.
`getSessions()` Returns `DialSession[]`	Returns detached views of the confirmed calls in the current queue, ended calls included. Each has a Trellus `sessionId`.
`getSession(sessionId)` Returns `DialSession \| null`	Returns one detached confirmed call view, or `null` when the session is unknown.
`subscribe(listener, { emitCurrent? })` Returns `() => void`	Calls the listener with each new snapshot. `emitCurrent: true` also delivers the current state once, right away. Returns an unsubscribe function.
`on(type, listener)` Returns `() => void`	Calls the listener for future typed events of that type. Returns an unsubscribe function.
`connect()` Returns `Promise<DialerSnapshot>`	Registers and prepares the transport, then resolves with the ready snapshot. Concurrent calls share one attempt.
`setTasks(tasks)` Returns `void`	Replaces the queue. Allowed only while no run, active call or wrap-up is pending.
`dial(task)` Returns `Promise<string>`	Starts one manual call. Resolves with its SDK `attemptId`.
`start({ mode?, lines? })` Returns `Promise<void>`	Starts a power or parallel scheduling pass. `mode` is `power` or `parallel`. Resolves after that pass, not when the list is finished. Watch snapshots for progress.
`pause()` Returns `void`	Stops new placement. Calls that were already dispatched stay active.
`resume()` Returns `Promise<void>`	Continues the last power or parallel run when no unknown call or wrap-up is unresolved.
`hangup(attemptId)` Returns `Promise<void>`	Asks the transport to end a known call. Waits for the transport to acknowledge the request, not for the call to finish.
`mute(attemptId, muted)` Returns `Promise<void>`	Sets the rep’s microphone mute through the transport.
`sendDigits(attemptId, digits)` Returns `Promise<void>`	Sends 1 to 64 keypad characters to a connected call. Accepts `0` to `9`, `*`, `#` and `w`.
`completeWrapUp(attemptId, disposition?)` Returns `Promise<void>`	Awaits `onDisposition`, clears that call’s wrap-up, then allows further scheduling.
`getAudioDevices()` Returns `Promise<AudioDevices>`	Resolves with `input` and `output` arrays of `{ deviceId, label }`, when the transport supports it.
`setInputDevice(id)` Returns `Promise<void>`	Selects a microphone through the transport.
`setOutputDevice(id)` Returns `Promise<void>`	Selects an output device through the transport or browser, when supported.
`destroy()` Returns `Promise<void>`	Stops placement, tries to end known calls, removes subscriptions and disposes owned audio. Repeat calls are harmless.

Power requires one line. Parallel requires at least two and cannot exceed the effective ceiling.
A manual call is available only with no active run, no active call and no pending wrap-up.
Other controls can reject with invalid_state when their prerequisites are absent.
Concurrent connect() calls share one in-flight promise. So do repeated completeWrapUp() calls while a save is pending.

completeWrapUp and onDisposition

completeWrapUp accepts an object with optional disposition and notes strings. Your onDisposition callback owns persistence. There is no implicit write to Trellus or to a CRM. A rejected callback leaves wrap-up pending. See wrap-up.

Snapshot shape

getSnapshot() and subscribe() deliver this object. It is detached from internal state.

DialerSnapshot

{
  status: 'idle' | 'connecting' | 'ready' | 'running' |
          'paused' | 'wrap_up' | 'error' | 'destroyed';
  mode: 'manual' | 'power' | 'parallel';
  lines: number;
  maxLines: number; // Configured cap, reduced by the transport's reported cap.
  tasks: Array<{
    id: string;
    phoneNumber: string;
    name?: string;
    status: 'queued' | 'dialing' | 'completed' | 'skipped' | 'failed';
    reason?: string;
  }>;
  calls: Array<{
    attemptId: string;
    taskId: string;
    sessionId?: string; // Trellus ID after confirmed session creation.
    phoneNumber: string;
    name?: string;
    status: 'creating' | 'ringing' | 'connected' | 'ending' |
            'ended' | 'failed' | 'unknown';
    muted: boolean;
    transcript: Array<{ id?: string; speaker?: string; text: string; isFinal: boolean }>;
    detection?: string;
    summary?: string;
    reason?: string;
  }>;
  pendingWrapUp: string[]; // SDK attempt IDs.
  error: null | { code: string; message: string; outcomeUnknown: boolean };
}

A task status of completed is local queue progress. It does not mean a task in your application was completed or a disposition was saved.
maxLines is the current client ceiling. It is available before connection and drops when the transport reports a smaller cap. lines is the requested width of the current run. Neither field grants entitlement.
pendingWrapUp holds SDK attempt IDs.
isFinal on a transcript segment and outcomeUnknown on an error are always booleans.
Snapshots contain contact phone numbers and transcript text. Handle them under your application’s data policy.
Snapshots never contain API keys, device tokens or transport session handles.

Errors and error codes

Methods that return a promise reject on failure, validation failures included. Both await with try and catch, and .catch(), work. Synchronous methods such as setTasks, pause, subscribe and on throw validation errors.

SDK validation errors are DialerError instances with a code and an outcomeUnknown flag. Snapshots and error events expose sanitized failures as { code, message, outcomeUnknown }.

Error types

interface DialerFailure { code: string; message: string; outcomeUnknown: boolean }

class DialerError extends Error {
  constructor(code: string, options?: { outcomeUnknown?: boolean });
  code: string;
  outcomeUnknown: boolean;
}

Common codes include not_ready, invalid_task, invalid_state, invalid_lines, no_tasks, unsupported, connection_lost, outcome_unknown and disposition_failed.

Use the code for program logic. Use the sanitized SDK message for user feedback.
invalid_state means a control was called while its prerequisites were absent.
connection_lost means the event stream for an active call could not be restored. The SDK keeps the call’s capacity as uncertain and never reports that it ended.
When outcomeUnknown is true, the call may have been placed. Do not retry it automatically. Read uncertain outcomes before you offer a Retry button.
Audio and device controls can also reject with errors from the audio provider. Do not show those messages to users or write them to telemetry.

Exported types

The root entry point exports createDialer, the DialerError class and these TypeScript types:

DialMode, DialTask, TransportTranscriptSegment, TranscriptSegment, AudioDevice, AudioDevices, TransportSession, DialCall, DialSession, DialerFailure, DialerCallEventContext, DialerSessionEventContext, DialerEventMap, DialerEvent, DialerSnapshot, TransportEvent, DialerTransport, Disposition, Dialer.

Event names and payloads are typed through DialerEventMap and DialerEvent. See Events and sessions. The transport types are covered in Custom transports.