# @sipgate/ai-flow-sdk

TypeScript SDK for building AI phone agents with [sipgate flow](https://www.sipgate.de/lp/ai-flow) — the **GDPR-compliant, EU-hosted real-time voice & telephony layer** that connects phone calls to your own AI agents. sipgate flow handles telephony, speech-to-text, and text-to-speech; you keep control of your conversation logic and choice of LLM.

## Installation

```bash
npm install @sipgate/ai-flow-sdk
# or
pnpm add @sipgate/ai-flow-sdk
```

**Requirements:** Node.js >= 22, TypeScript 5.x recommended

## Quick Start

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

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

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

  onUserSpeak: async (event) => {
    return `You said: ${event.text}`;
  },

  // Reported when something goes wrong during the call: an invalid action, an
  // unreachable speech provider, a failed synthesis. Branch on `event.code`
  // and use `event.severity` ("warning" | "error") to filter noise.
  onError: async (event) => {
    console.error(`[${event.severity}] ${event.code}: ${event.message}`);
    // Over HTTP you may also return an action here, e.g. transfer to a human
    // when synthesis is unavailable. Over WebSocket the event is diagnostic.
  },
});

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

The `onError` handler receives the [`error` event](https://sipgate.github.io/sipgate-ai-flow-api/api/events/error). It is additive — the existing `sms_failed` event and the `transfer_failed_reason` field on `session_start` are unchanged.

## Documentation

Full reference — events, actions, TTS providers, barge-in, outbound calls, and more:

**[sipgate.github.io/sipgate-ai-flow-api](https://sipgate.github.io/sipgate-ai-flow-api/)**

## License

Apache-2.0