---
title: "Dialer SDK API Reference: createDialer, Methods | Trellus"
description: "Reference for the JavaScript dialer SDK: createDialer options, the task shape, every dialer method, the snapshot shape, errors and error codes."
source: "https://www.trellus.ai/developers/dialer-sdk/api"
note: "Text-only copy of the page for AI assistants and agents. Link to the source address, not this file."
site_summary: "https://www.trellus.ai/llms.txt"
---

# 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.

@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

```typescript
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

```typescript
{
  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](https://www.trellus.ai/developers/dialer-sdk/lifecycle#wrap-up).

## Snapshot shape

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

DialerSnapshot

```typescript
{
  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

```typescript
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](https://www.trellus.ai/developers/dialer-sdk/lifecycle#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](https://www.trellus.ai/developers/dialer-sdk/events). The transport types are covered in [Custom transports](https://www.trellus.ai/developers/dialer-sdk/live-calling#custom-transport).