Server SDK

The Server SDK provides a type-safe Node.js client for the DialStack API. Use it to manage accounts, users, and create session tokens for embedded components.

Installation

Bash

npm install @dialstack/sdk-server

Quick Start

TypeScript

import { DialStack } from '@dialstack/sdk-server';

const dialstack = new DialStack(process.env.DIALSTACK_API_KEY);

// Create an account
const account = await dialstack.accounts.create({
  email: 'customer@example.com',
});

// Create a user (account context passed in options)
const user = await dialstack.users.create(
  { name: 'John Doe', email: 'john@example.com' },
  { dialstackAccount: account.id }
);

// Create a session for embedded components
const session = await dialstack.accountSessions.create({
  account: account.id,
  components: {
    call_logs: { enabled: true },
    voicemails: { enabled: true },
  },
});

// Return session to frontend
console.log(session.client_secret);

Configuration

Basic Configuration

TypeScript

const dialstack = new DialStack(process.env.DIALSTACK_API_KEY);

Advanced Configuration

TypeScript

const dialstack = new DialStack(process.env.DIALSTACK_API_KEY, {
  apiUrl: 'https://api.dialstack.ai', // Custom API URL
  timeout: 80000, // Request timeout (ms)
  maxNetworkRetries: 2, // Retry count
  telemetry: true, // Enable telemetry
  appInfo: {
    // Your app info (for User-Agent)
    name: 'MyApp',
    version: '1.0.0',
    url: 'https://myapp.com',
  },
});

DialStackConfig Options

Option	Type	Default	Description
apiUrl	string	https://api.dialstack.ai	API base URL
timeout	number	80000	Request timeout in ms
maxNetworkRetries	number	2	Max retry attempts on 5xx, 429, timeouts and network errors, for every method including creates
telemetry	boolean	true	Send usage telemetry
appInfo	AppInfo	-	Application identification

Resources

The client exposes one namespace per API resource, such as accounts, users, phoneNumbers, calls, dialPlans, ringGroups, devices and webhookEndpoints. These pages cover the most common ones:

Resource	Description
accounts	Create and manage customer accounts
users	Manage users within accounts
phoneNumbers	Manage an account's phone numbers
accountSessions, userSessions	Mint tokens for embedded components and softphones

The SDK reference lists every namespace, method and type.

Request Options

All methods accept an optional RequestOptions parameter:

TypeScript

const account = await dialstack.accounts.retrieve(accountId, {
  timeout: 30000, // Override timeout
  maxNetworkRetries: 5, // Override retries
});

RequestOptions

Option	Type	Description
timeout	number	Override request timeout
maxNetworkRetries	number	Override retry count
idempotencyKey	string	Sent as an Idempotency-Key header. No operation in the API reference reads it today, so it does not make retries safe; see Retries and idempotency.
dialstackAccount	string	Account context (for account-scoped ops)

Auto-Pagination

List methods return the first page when awaited, and offer auto-pagination helpers that follow next_page_url:

Iterate with autoPagingEach

TypeScript

for await (const account of dialstack.accounts.list().autoPagingEach()) {
  console.log(account.id);
}

Collect with autoPagingToArray

TypeScript

const accounts = await dialstack.accounts.list().autoPagingToArray({ limit: 100 });

console.log(`Found ${accounts.length} accounts`);

To follow page URLs yourself, see Pagination.

Event Listeners

Monitor SDK activity:

TypeScript

dialstack.on('request', (event) => {
  console.log(`${event.method} ${event.path}`);
});

dialstack.on('response', (event) => {
  console.log(`${event.statusCode} in ${event.elapsed}ms`);
});

Event Types

RequestEvent:

TypeScript

interface RequestEvent {
  method: string;
  path: string;
  dialstackAccount?: string;
  idempotencyKey?: string;
  requestStartTime: number;
}

ResponseEvent:

TypeScript

interface ResponseEvent {
  method: string;
  path: string;
  statusCode: number;
  requestId?: string;
  dialstackAccount?: string;
  elapsed: number;
}

Error Handling

The SDK throws typed errors:

TypeScript

import {
  DialStack,
  DialStackError,
  DialStackAuthenticationError,
  DialStackNotFoundError,
  DialStackRateLimitError,
} from '@dialstack/sdk-server';

try {
  await dialstack.accounts.retrieve('invalid_id');
} catch (error) {
  if (error instanceof DialStackNotFoundError) {
    console.log('Account not found');
  } else if (error instanceof DialStackAuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof DialStackRateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof DialStackError) {
    console.log('API error:', error.message);
  }
}

Error Classes

Error	HTTP Status	Description
DialStackAuthenticationError	401	Invalid API key
DialStackPermissionError	403	Access denied
DialStackNotFoundError	404	Resource not found
DialStackConflictError	409	Resource conflict
DialStackValidationError	400	Validation failed
DialStackInvalidRequestError	400	Invalid request
DialStackRateLimitError	429	Rate limit exceeded
DialStackAPIError	5xx	Server error
DialStackConnectionError	-	Network error

TypeScript

Full TypeScript support with exported types:

TypeScript

import { DialStack } from '@dialstack/sdk-server';
import type {
  Account,
  AccountCreateParams,
  User,
  UserCreateParams,
  AccountSessionCreateParams,
  AccountSessionCreateResponse,
  DialStackConfig,
  RequestOptions,
} from '@dialstack/sdk-server';

Next Steps

• Accounts - Manage accounts
• Users - Manage users
• Sessions - Create session tokens
• Authentication - API keys, session tokens and user tokens
• Making requests - Retries, idempotency and rate limits