@sinch/functions-runtime

Development runtime for Sinch Functions - build serverless voice applications with ease.

Installation

npm install @sinch/functions-runtime

Quick Start

Create a function.js file:

import { IceSvamlBuilder, MenuBuilder, MenuTemplates } from '@sinch/functions-runtime';

// Handle incoming calls
export async function ice(context, event) {
  return new IceSvamlBuilder()
    .say('Welcome to our service! Press 1 for sales, 2 for support.')
    .runMenu(MenuTemplates.business('Acme Corp').menus)
    .build();
}

// Handle menu selections
export async function pie(context, event) {
  const selection = event.menuResult?.value;

  if (selection === 'sales') {
    return new IceSvamlBuilder()
      .say('Connecting you to sales.')
      .connectPstn('+15551234567')
      .build();
  }

  return new IceSvamlBuilder()
    .say('Goodbye!')
    .hangup()
    .build();
}

Run locally:

npx sinch-runtime

Features

SVAML Builders

Build voice responses with a fluent API:

import { IceSvamlBuilder, AceSvamlBuilder, PieSvamlBuilder } from '@sinch/functions-runtime';

// ICE (Incoming Call Event) - handle incoming calls
const iceResponse = new IceSvamlBuilder()
  .say('Hello, welcome!')
  .connectPstn('+15551234567', {
    cli: '+15559999999',
    enableAce: true,
    enableDice: true
  })
  .build();

// ACE (Answered Call Event) - handle answered outbound calls
const aceResponse = new AceSvamlBuilder()
  .say('The call has been answered.')
  .continue()
  .build();

// PIE (Prompt Input Event) - handle user input
const pieResponse = new PieSvamlBuilder()
  .say('You pressed ' + selection)
  .hangup()
  .build();

Menu Builder

Create IVR menus with validation:

import { MenuBuilder, MenuTemplates, createMenu } from '@sinch/functions-runtime';

// Use pre-built templates
const businessMenu = MenuTemplates.business('Acme Corp');
const yesNoMenu = MenuTemplates.yesNo('Do you want to continue?');

// Or build custom menus
const customMenu = new MenuBuilder()
  .prompt('Press 1 for English, 2 for Spanish')
  .option('1', 'menu(english)')
  .option('2', 'menu(spanish)')
  .addSubmenu('english')
  .prompt('Press 1 for sales, 2 for support')
  .option('1', 'return(en-sales)')
  .option('2', 'return(en-support)')
  .build();

Cache

Store and retrieve data across function invocations:

import { LocalCache } from '@sinch/functions-runtime';

// In your function
export async function ice(context, event) {
  const cache = context.cache;

  // Store data
  await cache.set('call-count', 1, 3600); // TTL in seconds

  // Retrieve data
  const count = await cache.get('call-count');

  // Check existence
  if (await cache.has('call-count')) {
    // ...
  }
}

Configuration

Access environment variables and secrets:

import { createConfig } from '@sinch/functions-runtime';

export async function ice(context, event) {
  const config = createConfig(context);

  // Get variables
  const companyName = config.getVariable('COMPANY_NAME', 'Default');

  // Get secrets
  const apiKey = config.getSecret('API_KEY');

  // Require variables (throws if missing)
  const required = config.requireVariable('IMPORTANT_VAR');
}

Voice Callbacks

| Callback | Description | Returns | |----------|-------------|---------| | ice | Incoming Call Event - first callback for incoming calls | SVAML | | ace | Answered Call Event - when outbound call is answered | SVAML | | pie | Prompt Input Event - user input (DTMF/voice) | SVAML | | dice | Disconnected Call Event - call ended | None | | notify | Notification events | None |

TypeScript Support

Full TypeScript support with comprehensive types:

import type {
  FunctionContext,
  IceCallbackData,
  AceCallbackData,
  PieCallbackData,
  SvamletResponse
} from '@sinch/functions-runtime';

export async function ice(
  context: FunctionContext,
  event: IceCallbackData
): Promise<SvamletResponse> {
  // Full type safety and IntelliSense!
}

API Reference

Builders

• IceSvamlBuilder - Build ICE responses
• AceSvamlBuilder - Build ACE responses
• PieSvamlBuilder - Build PIE responses
• MenuBuilder - Build IVR menus
• MenuTemplates - Pre-built menu templates

Cache

• IFunctionCache - Cache interface
• LocalCache - In-memory cache (development)

Configuration

• UniversalConfig - Configuration utility
• createConfig() - Create config instance

Types

All callback data types, SVAML types, and handler types are exported for TypeScript users.

License

MIT