API Reference

Complete API documentation for the AiFlowAssistant class.

AiFlowAssistant

The main class for creating AI voice assistants.

AiFlowAssistant.create(options)

Creates a new assistant instance.

Options:

interface AiFlowAssistantOptions {
  // Bearer token for outbound call API requests
  token?: string;

  // Base URL of the sipgate API (default: "https://api.sipgate.com")
  baseUrl?: string;

  // Enable debug logging
  debug?: boolean;

  // Event handlers
  onSessionStart?: (
    event: AiFlowEventSessionStart
  ) => Promise<InvocationResponseType>;

  onUserSpeak?: (
    event: AiFlowEventUserSpeak
  ) => Promise<InvocationResponseType>;

  onAssistantSpeak?: (
    event: AiFlowEventAssistantSpeak
  ) => Promise<InvocationResponseType>;

  onAssistantSpeechEnded?: (
    event: AiFlowEventAssistantSpeechEnded
  ) => Promise<InvocationResponseType>;

  onUserInputTimeout?: (
    event: AiFlowEventUserInputTimeout
  ) => Promise<InvocationResponseType>;

  onSessionEnd?: (
    event: AiFlowEventSessionEnd
  ) => Promise<InvocationResponseType>;

  // DEPRECATED: Use onUserSpeak instead
  onUserBargeIn?: (
    event: AiFlowEventUserBargeIn
  ) => Promise<InvocationResponseType>;
}

type InvocationResponseType = AiFlowAction | string | null | undefined;

Example:

const assistant = AiFlowAssistant.create({
  debug: true,
  apiKey: process.env.API_KEY,

  onSessionStart: async (event) => {
    return "Welcome!";
  },

  onUserSpeak: async (event) => {
    return "Hello!";
  },
});

Instance Methods

assistant.express()

Returns an Express.js middleware function for handling webhook requests.

app.post("/webhook", assistant.express());

Usage:

import express from "express";
import { AiFlowAssistant } from "@sipgate/ai-flow-sdk";

const app = express();
app.use(express.json());

const assistant = AiFlowAssistant.create({
  onUserSpeak: async (event) => {
    return "Hello!";
  },
});

app.post("/webhook", assistant.express());

assistant.ws(websocket)

Returns a WebSocket message handler.

wss.on("connection", (ws) => {
  ws.on("message", assistant.ws(ws));
});

Usage:

import WebSocket from "ws";
import { AiFlowAssistant } from "@sipgate/ai-flow-sdk";

const wss = new WebSocket.Server({ port: 8080 });

const assistant = AiFlowAssistant.create({
  onUserSpeak: async (event) => {
    return "Hello!";
  },
});

wss.on("connection", (ws) => {
  ws.on("message", assistant.ws(ws));
});

assistant.call(params)

Initiates an outbound call. Requires token to be set in options.

await assistant.call({
  aiFlowId: string;      // ID of the AI flow
  billingDevice: string; // Billing device suffix (provided during onboarding)
  toPhoneNumber: string; // Target number in E.164 format
});

Returns Promise<void>. Throws on API errors (e.g. flow not found, missing phone number configuration).

See Outbound Calls for a full guide.

assistant.onEvent(event)

Manually process an event (useful for custom integrations).

const action = await assistant.onEvent(event);

Usage:

import { AiFlowAssistant } from "@sipgate/ai-flow-sdk";

const assistant = AiFlowAssistant.create({
  onUserSpeak: async (event) => {
    return "Hello!";
  },
});

// Custom integration
app.post("/custom-webhook", async (req, res) => {
  const event = req.body;
  const action = await assistant.onEvent(event);

  if (action) {
    res.json(action);
  } else {
    res.status(204).send();
  }
});

Options Reference

token?: string

Bearer token for authenticating outbound call API requests. Required when using assistant.call().

baseUrl?: string

Base URL of the sipgate API. Defaults to "https://api.sipgate.com". Override for custom environments.

debug?: boolean

Enable debug logging. When true, the SDK will log all events and actions to the console.

const assistant = AiFlowAssistant.create({
  debug: true, // Logs all events and actions
  // ...
});

Event Handlers

All event handlers are optional and follow the same pattern:

onEventName?: (event: EventType) => Promise<InvocationResponseType>

See the Event Types documentation for details on each event.

Type Definitions

InvocationResponseType

The return type for all event handlers:

type InvocationResponseType =
  | AiFlowAction  // Action object
  | string           // Simple string (converted to speak action)
  | null             // No response
  | undefined;       // No response

Error Handling

The SDK handles errors gracefully. If an event handler throws an error, it will be logged and the SDK will continue processing other events.

const assistant = AiFlowAssistant.create({
  onUserSpeak: async (event) => {
    try {
      return await processUserInput(event.text);
    } catch (error) {
      console.error("Error:", error);
      return "I'm sorry, I encountered an error.";
    }
  },
});

Next Steps

• Event Types - Complete event reference
• Action Types - All available actions
• Integration Guides - Integration examples