SDK Guide

Welcome to the sipgate AI Flow SDK documentation! This guide will help you build powerful AI-powered voice assistants with real-time speech processing capabilities.

What is the SDK?

The @sipgate/ai-flow-sdk is a TypeScript SDK that provides a simple, event-driven interface for building voice assistants. It handles the complexity of real-time speech processing, event management, and action responses, so you can focus on building great conversational experiences.

Key Concepts

Event-Driven Architecture

The SDK uses an event-driven model where your assistant responds to events from the AI Flow service:

• Session Start - When a new call begins
• User Speak - When the user says something
• User Barge In - When the user interrupts the assistant
• Assistant Speak - After your assistant speaks
• Session End - When the call ends

Simple Response Model

Event handlers can return:

• Simple strings - Automatically converted to speech
• Action objects - For advanced control (speak, transfer, hangup, etc.)
• null/undefined - No response needed

Easy Integration

The SDK provides built-in middleware for:

• Express.js - assistant.express() middleware
• WebSocket - assistant.ws(ws) message handler
• Custom - assistant.onEvent(event) for any integration

Quick Example

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

const assistant = AiFlowAssistant.create({
  onSessionStart: async (event) => {
    return "Hello! How can I help you today?";
  },

  onUserSpeak: async (event) => {
    const userText = event.text;
    console.log(`User said: ${userText}`);
    return `You said: ${userText}`;
  },

  onSessionEnd: async (event) => {
    console.log(`Session ${event.session.id} ended`);
  },
});

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

What's Next?

• Installation - Install the SDK and set up your project
• Quick Start - Build your first voice assistant
• Core Concepts - Learn about events and responses
• API Reference - Complete API documentation

For AI-Assisted Development

Using AI coding assistants like Claude Code, ChatGPT, or Cursor? Download our LLM Reference - a single-file reference containing all API and SDK knowledge optimized for code generation.