Sipgate AI Flow SDK

https://www.npmjs.com/package/@sipgate/ai-flow-sdk
Admin
An official TypeScript SDK for building AI-powered voice assistants with real-time speech processing...
Tokens:91,335
Snippets:643
Trust Score:9.6
Update:10 months ago
Show doc for...
Tokens:
Raw
### Basic Assistant Setup with @sipgate/ai-flow-sdk

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk_activeTab=code

Demonstrates the basic setup of an AI Flow Assistant using the SDK. It configures event handlers for session start, user speaking, session end, and user barge-in. This example requires Node.js and the ai-flow-sdk package.

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

const assistant = AiFlowAssistant.create({
  debug: true,

  onSessionStart: async (event) => {
    console.log(`Session started for ${event.session.phone_number}`);
    return "Hello! How can I help you today?";
  },

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

    // Process user input and return response
    return `You said: ${userText}`;
  },

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

  onUserBargeIn: async (event) => {
    console.log(`User interrupted with: ${event.text}`);
    return "I'm listening, please continue.";
  },
});
```

--------------------------------

### WebSocket Integration Example

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk/v/1.0_activeTab=dependents

An example demonstrating how to integrate the ai-flow-sdk using WebSockets, showing how to set up a WebSocket server and handle incoming messages.

```APIDOC
## WebSocket Integration

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

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

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

wss.on("connection", (ws, req) => {
  console.log("New WebSocket connection");

  ws.on("message", assistant.ws(ws));

  ws.on("error", (error) => {
    console.error("WebSocket error:", error);
  });

  ws.on("close", () => {
    console.log("WebSocket connection closed");
  });
});

console.log("WebSocket server listening on port 8080");
```
```

--------------------------------

### Express.js Integration Example

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk/v/1.0_activeTab=dependents

A complete example demonstrating how to integrate the ai-flow-sdk with Express.js, including setting up the assistant, handling webhooks, and basic error handling.

```APIDOC
## Express.js Integration

Complete example with error handling and logging:

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

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

const assistant = AiFlowAssistant.create({
  debug: process.env.NODE_ENV !== "production",

  onSessionStart: async (event) => {
    return "Welcome! How can I help you today?";
  },

  onUserSpeak: async (event) => {
    // Your conversation logic here
    return processUserInput(event.text);
  },

  onSessionEnd: async (event) => {
    await cleanupSession(event.session.id);
  },
});

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

// Health check
app.get("/health", (req, res) => {
  res.json({ status: "ok" });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`AI Flow assistant running on port ${PORT}`);
});
```
```

--------------------------------

### Speak Action: Simple Text, SSML, and Custom TTS Examples

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk_activeTab=code

Demonstrates the Speak action, used to have the AI Flow service speak to the user. Examples cover speaking plain text, using SSML for advanced control, and configuring a custom TTS provider like Azure.

```javascript
// Simple text
return {
  type: AiFlowActionType.SPEAK,
  session_id: event.session.id,
  text: "Hello, how can I help you?",
};

// With SSML
return {
  type: AiFlowActionType.SPEAK,
  session_id: event.session.id,
  ssml: `
    <speak>
      <prosody rate="slow">Please listen carefully.</prosody>
      <break time="500ms"/>
      Your account balance is <say-as interpret-as="currency">$42.50</say-as>
    </speak>
  `,
};

// With custom TTS provider
return {
  type: AiFlowActionType.SPEAK,
  session_id: event.session.id,
  text: "Hello in a different voice",
  tts: {
    provider: TtsProvider.AZURE,
    language: "en-US",
    voice: "en-US-JennyNeural",
  },
};
```

--------------------------------

### Install @sipgate/ai-flow-sdk with npm, yarn, or pnpm

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk/v/1.0_activeTab=dependencies

Demonstrates how to install the SDK using different package managers. Requires Node.js >= 22.0.0 and TypeScript 5.x.

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

--------------------------------

### POST /webhook - Direct Integration Example

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk/v/1.0

Handles incoming events from the ai-flow service and constructs appropriate actions. This example demonstrates how to process different event types like 'session_start', 'user_speak', 'user_barge_in', 'assistant_speak', and 'session_end'. It shows how to generate actions such as SPEAK, TRANSFER, and HANGUP based on the received event data.

```APIDOC
## POST /webhook

### Description
This endpoint receives webhook events from the ai-flow service and responds with an action to perform. It handles various event types to control the flow of the voice interaction.

### Method
POST

### Endpoint
/webhook

#### Request Body
- **event** (object) - Required - The incoming event object from the ai-flow service.
  - **type** (string) - Required - The type of the event (e.g., 'session_start', 'user_speak').
  - **session** (object) - Required - Information about the current session.
    - **id** (string) - Required - The unique identifier for the session.
  - **text** (string) - Optional - The text spoken by the user (for 'user_speak' and 'user_barge_in' events).
  - **duration_ms** (number) - Optional - The duration in milliseconds the assistant spoke (for 'assistant_speak' events).

### Request Example
```json
{
  "type": "user_speak",
  "session": {
    "id": "sess_12345abc"
  },
  "text": "I want to talk to support"
}
```

### Response
#### Success Response (200 OK)
- **action** (object) - The action to be performed by the ai-flow service.
  - **type** (string) - Required - The type of action (e.g., 'speak', 'transfer', 'hangup').
  - **session_id** (string) - Required - The session ID the action pertains to.
  - **text** (string) - Optional - Text to be spoken by the assistant.
  - **target_phone_number** (string) - Optional - Phone number to transfer the call to.
  - **caller_id_name** (string) - Optional - Caller ID name for transfers.
  - **caller_id_number** (string) - Optional - Caller ID number for transfers.
  - **barge_in** (object) - Optional - Barge-in configuration for speaking actions.
    - **strategy** (string) - Required - The barge-in strategy (e.g., 'minimum_characters').
    - **minimum_characters** (number) - Required - The minimum number of characters to trigger barge-in.

#### Response Example
```json
{
  "type": "transfer",
  "session_id": "sess_12345abc",
  "target_phone_number": "+1234567890",
  "caller_id_name": "Support",
  "caller_id_number": "+1234567890"
}
```

#### Success Response (204 No Content)
Sent when no action is to be performed.

#### Error Response (400 Bad Request)
- **error** (string) - Description of the error.

### Event-Action Flow
- **session_start**: Respond with speak/audio or do nothing.
- **user_speak**: Respond with speak/audio/transfer/hangup/dtmf.
- **user_barge_in**: Optional: respond with speak to acknowledge.
- **assistant_speak**: Optional: track metrics, trigger next action.
- **session_end**: Cleanup only, no actions accepted.
```

--------------------------------

### Speak Action - Text, SSML, and TTS Configuration Examples

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk

Demonstrates how to use the Speak action to respond to the user with plain text or SSML. Includes examples for basic text, SSML markup for controlled speech, and custom TTS provider configurations.

```typescript
// Simple text
return {
  type: AiFlowActionType.SPEAK,
  session_id: event.session.id,
  text: "Hello, how can I help you?",
};

// With SSML
return {
  type: AiFlowActionType.SPEAK,
  session_id: event.session.id,
  ssml: "
    <speak>
      <prosody rate=\"slow\">Please listen carefully.</prosody>
      <break time=\"500ms"/>
      Your account balance is <say-as interpret-as=\"currency\">$42.50</say-as>
    </speak>
  ",
};

// With custom TTS provider
return {
  type: AiFlowActionType.SPEAK,
  session_id: event.session.id,
  text: "Hello in a different voice",
  tts: {
    provider: TtsProvider.AZURE,
    language: "en-US",
    voice: "en-US-JennyNeural",
  },
};
```

--------------------------------

### Advanced Customer Service Bot with AI Flow SDK

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk_activeTab=code

An advanced example of a customer service bot using the AI Flow SDK, demonstrating state management with a Map and intent routing based on user input. It handles session start, user speech, user barge-in, and session end, including transferring calls and providing default responses.

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

// Session state management
const sessions = new Map<string, { state: string; data: any }>();

const assistant = AiFlowAssistant.create({
  debug: true,

  onSessionStart: async (event) => {
    // Initialize session state
    sessions.set(event.session.id, {
      state: "greeting",
      data: { attempts: 0 },
    });

    return {
      type: "speak",
      session_id: event.session.id,
      text: "Welcome to customer support. How can I help you today? You can ask about billing, technical support, or sales.",
      barge_in: {
        strategy: BargeInStrategy.MINIMUM_CHARACTERS,
        minimum_characters: 3,
      },
    };
  },

  onUserSpeak: async (event) => {
    const session = sessions.get(event.session.id);
    if (!session) return null;

    const text = event.text.toLowerCase();

    // Intent routing
    if (text.includes("billing") || text.includes("invoice")) {
      return {
        type: "transfer",
        session_id: event.session.id,
        target_phone_number: "+1234567890",
        caller_id_name: "Billing Department",
        caller_id_number: "+1234567890",
      };
    }

    if (text.includes("goodbye") || text.includes("bye")) {
      return {
        type: "speak",
        session_id: event.session.id,
        text: "Thank you for calling. Have a great day!",
        barge_in: { strategy: BargeInStrategy.NONE }, // Don't allow interruption
      };
    }

    if (text.includes("technical") || text.includes("support")) {
      session.state = "technical_support";
      return "I'll connect you with our technical support team. Please describe your issue.";
    }

    // Default response
    session.data.attempts++;
    if (session.data.attempts > 2) {
      return "I'm having trouble understanding. Let me transfer you to a representative.";
    }

    return "I can help with billing, technical support, or sales. Which would you like?";
  },

  onUserBargeIn: async (event) => {
    console.log(`User interrupted: ${event.text}`);
    return "Yes, I'm listening.";
  },

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

const app = express();
app.use(express.json());
app.post("/webhook", assistant.express());

app.listen(3000, () => {
  console.log("Customer service bot running on port 3000");
});
```

--------------------------------

### SessionStart Event Interface and Example

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk_activeTab=code

Defines the structure of the SessionStart event, triggered when a new call session begins. It includes session details like ID, account ID, phone numbers, and call direction. The example shows how to log session information and return a greeting.

```typescript
interface AiFlowApiEventSessionStart {
  type: "session_start";
  session: {
    id: string; // UUID of the session
    account_id: string; // Account identifier
    phone_number: string; // Phone number for this flow session
    direction?: "inbound" | "outbound"; // Call direction
    from_phone_number: string; // Phone number of the caller
    to_phone_number: string; // Phone number of the callee
  };
}
```

```javascript
onSessionStart: async (event) => {
  // Log session details
  console.log(`${event.session.direction} call from ${event.session.from_phone_number} to ${event.session.to_phone_number}`);

  // Return greeting
  return "Welcome to our service!";
};
```

--------------------------------

### AssistantSpeak Event Interface and Example

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk

Defines the structure for the AssistantSpeak event, triggered after the assistant starts speaking. Includes spoken text, SSML, duration, and timestamps. The example demonstrates logging speech duration and tracking conversation metrics.

```typescript
interface AiFlowApiEventAssistantSpeak {
  type: "assistant_speak";
  text?: string; // Text that was spoken
  ssml?: string; // SSML that was used (if applicable)
  duration_ms: number; // Duration of speech in milliseconds
  speech_started_at: number; // Unix timestamp (ms) when speech started
  session: SessionInfo;
}

onAssistantSpeak: async (event) => {
  console.log(`Spoke for ${event.duration_ms}ms`);

  // Track conversation metrics
  trackMetrics({
    sessionId: event.session.id,
    duration: event.duration_ms,
    text: event.text,
  });
};
```

--------------------------------

### ElevenLabs Voice Configuration Examples (TypeScript)

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk_activeTab=dependents

Illustrates two ways to configure the ElevenLabs TTS provider in code: using a specific voice ID or by a human-readable voice name. These examples demonstrate the practical application of the TtsProviderConfigElevenLabs interface.

```typescript
// Using voice ID
provider: {
  provider: TtsProvider.ELEVEN_LABS,
  voice: { id: "21m00Tcm4TlvDq8ikWAM" }  // Rachel
}

// Using voice name
provider: {
  provider: TtsProvider.ELEVEN_LABS,
  voice: { name: "Rachel" }
}
```

--------------------------------

### Handle Events and Construct Actions with Express.js

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk/v/1.0_activeTab=dependencies

This example shows how to set up an Express.js webhook to receive events from the AI Flow SDK and respond with appropriate actions like SPEAK, TRANSFER, or HANGUP. It handles various event types including session start, user input, and session end. Dependencies include 'express' and '@sipgate/ai-flow-sdk'.

```javascript
import express from "express";
import { AiFlowEventType, AiFlowActionType } from "@sipgate/ai-flow-sdk";

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

app.post("/webhook", async (req, res) => {
  const event = req.body;

  let action = null;

  switch (event.type) {
    case "session_start":
      action = {
        type: AiFlowActionType.SPEAK,
        session_id: event.session.id,
        text: "Welcome to our service!",
        barge_in: {
          strategy: "minimum_characters",
          minimum_characters: 5,
        },
      };
      break;

    case "user_speak":
      if (event.text.toLowerCase().includes("transfer")) {
        action = {
          type: AiFlowActionType.TRANSFER,
          session_id: event.session.id,
          target_phone_number: "+1234567890",
          caller_id_name: "Support",
          caller_id_number: "+1234567890",
        };
      } else if (event.text.toLowerCase().includes("goodbye")) {
        action = {
          type: AiFlowActionType.HANGUP,
          session_id: event.session.id,
        };
      } else {
        action = {
          type: AiFlowActionType.SPEAK,
          session_id: event.session.id,
          text: `You said: ${event.text}`,
        };
      }
      break;

    case "user_barge_in":
      console.log(`User interrupted with: ${event.text}`);
      action = {
        type: AiFlowActionType.SPEAK,
        session_id: event.session.id,
        text: "I'm listening, go ahead.",
      };
      break;

    case "assistant_speak":
      console.log(`Spoke for ${event.duration_ms}ms`);
      // Optional: track metrics, no action needed
      break;

    case "session_end":
      console.log(`Session ${event.session.id} ended`);
      // Cleanup logic, no action needed
      break;
  }

  // Return action if one was created
  if (action) {
    res.json(action);
  } else {
    res.status(204).send();
  }
});

app.listen(3000, () => {
  console.log("Webhook server listening on port 3000");
});

```

--------------------------------

### WebSocket Integration

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk/v/1.0_activeTab=code

Integrate the AI Flow SDK with a WebSocket server. This example shows how to handle incoming WebSocket messages and respond using the SDK.

```APIDOC
## WebSocket Integration

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

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

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

wss.on("connection", (ws, req) => {
  console.log("New WebSocket connection");

  ws.on("message", assistant.ws(ws));

  ws.on("error", (error) => {
    console.error("WebSocket error:", error);
  });

  ws.on("close", () => {
    console.log("WebSocket connection closed");
  });
});

console.log("WebSocket server listening on port 8080");
```
```

--------------------------------

### SessionStart Event Interface and Example

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk

Defines the structure for the SessionStart event, triggered when a new call session begins. Includes session details like ID, account ID, and phone numbers. The example demonstrates logging session information and returning a greeting.

```typescript
interface AiFlowApiEventSessionStart {
  type: "session_start";
  session: {
    id: string; // UUID of the session
    account_id: string; // Account identifier
    phone_number: string; // Phone number for this flow session
    direction?: "inbound" | "outbound"; // Call direction
    from_phone_number: string; // Phone number of the caller
    to_phone_number: string; // Phone number of the callee
  };
}

onSessionStart: async (event) => {
  // Log session details
  console.log(`${event.session.direction} call from ${event.session.from_phone_number} to ${event.session.to_phone_number}`);

  // Return greeting
  return "Welcome to our service!";
};
```

--------------------------------

### UserSpeak Event Interface and Example

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk_activeTab=code

Defines the UserSpeak event, triggered when user speech is recognized. It includes the recognized text and session information. The example demonstrates analyzing user intent and responding accordingly or processing the input.

```typescript
interface AiFlowApiEventUserSpeak {
  type: "user_speak";
  text: string; // Recognized speech text
  session: {
    id: string;
    account_id: string;
    phone_number: string;
  };
}
```

```javascript
onUserSpeak: async (event) => {
  const intent = analyzeIntent(event.text);

  if (intent === "help") {
    return "I can help you with billing, support, or sales.";
  }

  return processUserInput(event.text);
};
```

--------------------------------

### Example: SPEAK Action with MINIMUM_CHARACTERS Barge-In (TypeScript)

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk/v/1.0_activeTab=dependencies

Demonstrates constructing a SPEAK action with the MINIMUM_CHARACTERS barge-in strategy, including a protection period. This example sets a high character threshold and a 2-second delay before allowing interruptions.

```typescript
return {
  type: AiFlowActionType.SPEAK,
  session_id: event.session.id,
  text: "Your account number is 1234567890. Please write this down.",
  barge_in: {
    strategy: BargeInStrategy.MINIMUM_CHARACTERS,
    minimum_characters: 10, // Require substantial speech
    allow_after_ms: 2000, // Protect first 2 seconds
  },
};
```

--------------------------------

### AssistantSpeak Event Interface and Example

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk_activeTab=code

Defines the AssistantSpeak event, occurring after the assistant begins speaking. It provides details about the spoken text, SSML (if used), duration, and timestamps. The example shows logging the duration and tracking conversation metrics.

```typescript
interface AiFlowApiEventAssistantSpeak {
  type: "assistant_speak";
  text?: string; // Text that was spoken
  ssml?: string; // SSML that was used (if applicable)
  duration_ms: number; // Duration of speech in milliseconds
  speech_started_at: number; // Unix timestamp (ms) when speech started
  session: SessionInfo;
}
```

```javascript
onAssistantSpeak: async (event) => {
  console.log(`Spoke for ${event.duration_ms}ms`);

  // Track conversation metrics
  trackMetrics({
    sessionId: event.session.id,
    duration: event.duration_ms,
    text: event.text,
  });
};
```

--------------------------------

### Create a Basic AiFlowAssistant in TypeScript

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk/v/1.0_activeTab=dependencies

Illustrates the creation of a basic AI Flow assistant using the `AiFlowAssistant.create` method. It configures event handlers for session start, user input, and session end, with options for debugging.

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

const assistant = AiFlowAssistant.create({
  debug: true,

  onSessionStart: async (event) => {
    console.log(`Session started for ${event.session.phone_number}`);
    return "Hello! How can I help you today?";
  },

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

    // Process user input and return response
    return `You said: ${userText}`;
  },

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

--------------------------------

### Create Audio Action in TypeScript

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk/v/1.0_activeTab=code

This snippet shows how to create an 'audio' action to play pre-recorded audio, such as WAV files (base64 encoded), to the user. It also includes an example of configuring barge-in behavior.

```typescript
// Play hold music or pre-recorded message
return {
  type: AiFlowActionType.AUDIO,
  session_id: event.session.id,
  audio: base64EncodedWavData,
  barge_in: {
    strategy: BargeInStrategy.MINIMUM_CHARACTERS,
    minimum_characters: 3,
  },
};
```

--------------------------------

### Handle SessionStart Event in TypeScript

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk/v/1.0_activeTab=dependents

Provides an example of how to handle the 'session_start' event. The handler logs the caller's phone number and returns a greeting message.

```typescript
onSessionStart: async (event) => {
  // Log session details
  console.log(`New call from ${event.session.phone_number}`);

  // Return greeting
  return "Welcome to our service!";
};
```

--------------------------------

### AssistantSpeechEnded Event Interface and Example

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk

Defines the structure for the AssistantSpeechEnded event, triggered after the assistant finishes speaking. Includes session information. The example shows logging the completion of speech for a session.

```typescript
interface AiFlowEventAssistantSpeechEnded {
  type: "assistant_speech_ended";
  session: SessionInfo;
}

onAssistantSpeechEnded: async (event) => {
  console.log(`Finished speaking for session ${event.session.id}`);

  // Hangup if needed
};
```

--------------------------------

### Implement Speak Action in JavaScript

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk/v/1.0_activeTab=versions

This example demonstrates how to implement the Speak action, which allows the AI Flow service to speak text or SSML to the user. It includes variations for plain text, SSML, and custom TTS providers.

```javascript
// Simple text
return {
  type: AiFlowActionType.SPEAK,
  session_id: event.session.id,
  text: "Hello, how can I help you?",
};

// With SSML
return {
  type: AiFlowActionType.SPEAK,
  session_id: event.session.id,
  ssml: "\n    <speak>\n      <prosody rate=\"slow\">Please listen carefully.</prosody>\n      <break time=\"500ms"/>\n      Your account balance is <say-as interpret-as=\"currency\">$42.50</say-as>\n    </speak>\n  ",
};

// With custom TTS provider
return {
  type: AiFlowActionType.SPEAK,
  session_id: event.session.id,
  text: "Hello in a different voice",
  provider: {
    provider: TtsProvider.AZURE,
    language: "en-US",
    voice: "en-US-JennyNeural",
  },
};
```

--------------------------------

### Handle SessionStart Event in AI Flow SDK

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk/v/1.0_activeTab=versions

Defines the structure of a SessionStart event and provides an example of an onSessionStart handler that logs the caller's phone number and returns a greeting.

```typescript
interface AiFlowApiEventSessionStart {
  type: "session_start";
  session: {
    id: string; // UUID of the session
    account_id: string; // Account identifier
    phone_number: string; // Caller's phone number
  };
}

onSessionStart: async (event) => {
  // Log session details
  console.log(`New call from ${event.session.phone_number}`);

  // Return greeting
  return "Welcome to our service!";
};
```

--------------------------------

### AiFlowApiEventSessionStart Interface

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk/v/1.0_activeTab=dependencies

Defines the structure of the `session_start` event, including session and account identifiers, and the caller's phone number. Includes an example handler.

```typescript
interface AiFlowApiEventSessionStart {
  type: "session_start";
  session: {
    id: string; // UUID of the session
    account_id: string; // Account identifier
    phone_number: string; // Caller's phone number
  };
}

// Example:
onSessionStart: async (event) => {
  // Log session details
  console.log(`New call from ${event.session.phone_number}`);

  // Return greeting
  return "Welcome to our service!";
};
```

--------------------------------

### AssistantSpeechEnded Event Interface and Example

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk_activeTab=code

Defines the AssistantSpeechEnded event, triggered after the assistant finishes speaking. It includes session information. The example shows logging the completion of speech for a session and includes a placeholder for hanging up.

```typescript
interface AiFlowEventAssistantSpeechEnded {
  type: "assistant_speech_ended";
  session: SessionInfo;
}
```

```javascript
onAssistantSpeechEnded: async (event) => {
  console.log(`Finished speaking for session ${event.session.id}`);

  // Hangup if needed
};
```

--------------------------------

### Speak Action Examples (JavaScript)

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/index

Demonstrates how to create Speak actions to make the AI Flow service speak text or SSML to the user. Supports plain text, SSML markup, and custom TTS provider settings. Dependencies include AiFlowActionType and TtsProvider enum. Inputs are event object, session ID, and text/SSML. Outputs are AiFlowActionSpeak objects.

```javascript
// Simple text
return {
  type: AiFlowActionType.SPEAK,
  session_id: event.session.id,
  text: "Hello, how can I help you?",
};
```

```javascript
// With SSML
return {
  type: AiFlowActionType.SPEAK,
  session_id: event.session.id,
  ssml: `
    <speak>
      <prosody rate="slow">Please listen carefully.</prosody>
      <break time="500ms"/>
      Your account balance is <say-as interpret-as="currency">$42.50</say-as>
    </speak>
  `,
};
```

```javascript
// With custom TTS provider
return {
  type: AiFlowActionType.SPEAK,
  session_id: event.session.id,
  text: "Hello in a different voice",
  tts: {
    provider: TtsProvider.AZURE,
    language: "en-US",
    voice: "en-US-JennyNeural",
  },
};
```

--------------------------------

### Customer Service Bot with State Management and Routing

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/index

This advanced example demonstrates building a customer service bot using the AI Flow Assistant. It includes session state management using a Map, intent routing based on user input (billing, technical support, sales), and handling of conversation flow and session termination.

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

// Session state management
const sessions = new Map<string, { state: string; data: any }>();

const assistant = AiFlowAssistant.create({
  debug: true,

  onSessionStart: async (event) => {
    // Initialize session state
    sessions.set(event.session.id, {
      state: "greeting",
      data: { attempts: 0 },
    });

    return {
      type: "speak",
      session_id: event.session.id,
      text: "Welcome to customer support. How can I help you today? You can ask about billing, technical support, or sales.",
      barge_in: {
        strategy: BargeInStrategy.MINIMUM_CHARACTERS,
        minimum_characters: 3,
      },
    };
  },

  onUserSpeak: async (event) => {
    const session = sessions.get(event.session.id);
    if (!session) return null;

    const text = event.text.toLowerCase();

    // Intent routing
    if (text.includes("billing") || text.includes("invoice")) {
      return {
        type: "transfer",
        session_id: event.session.id,
        target_phone_number: "+1234567890",
        caller_id_name: "Billing Department",
        caller_id_number: "+1234567890",
      };
    }

    if (text.includes("goodbye") || text.includes("bye")) {
      return {
        type: "speak",
        session_id: event.session.id,
        text: "Thank you for calling. Have a great day!",
        barge_in: { strategy: BargeInStrategy.NONE }, 
      };
    }

    if (text.includes("technical") || text.includes("support")) {
      session.state = "technical_support";
      return "I'll connect you with our technical support team. Please describe your issue.";
    }

    // Default response
    session.data.attempts++;
    if (session.data.attempts > 2) {
      return "I'm having trouble understanding. Let me transfer you to a representative.";
    }

    return "I can help with billing, technical support, or sales. Which would you like?";
  },

  onUserBargeIn: async (event) => {
    console.log(`User interrupted: ${event.text}`);
    return "Yes, I'm listening.";
  },

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

const app = express();
app.use(express.json());
app.post("/webhook", assistant.express());

app.listen(3000, () => {
  console.log("Customer service bot running on port 3000");
});
```

--------------------------------

### Express.js Integration

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk/v/1.0_activeTab=code

Integrate the AI Flow SDK with an Express.js application. This example demonstrates setting up a webhook endpoint for handling AI Flow events.

```APIDOC
## Express.js Integration

Complete example with error handling and logging:

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

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

const assistant = AiFlowAssistant.create({
  debug: process.env.NODE_ENV !== "production",

  onSessionStart: async (event) => {
    return "Welcome! How can I help you today?";
  },

  onUserSpeak: async (event) => {
    // Your conversation logic here
    return processUserInput(event.text);
  },

  onSessionEnd: async (event) => {
    await cleanupSession(event.session.id);
  },
});

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

// Health check
app.get("/health", (req, res) => {
  res.json({ status: "ok" });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`AI Flow assistant running on port ${PORT}`);
});
```
```

--------------------------------

### Speak Action - Text and SSML Examples (TypeScript)

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk/v/1.0

Demonstrates how to create Speak actions, either with plain text or SSML markup, for the AI Flow service to speak to the user. It requires a session ID and either text or SSML content.

```typescript
// Simple text
return {
  type: AiFlowActionType.SPEAK,
  session_id: event.session.id,
  text: "Hello, how can I help you?",
};

// With SSML
return {
  type: AiFlowActionType.SPEAK,
  session_id: event.session.id,
  ssml: `
    <speak>
      <prosody rate="slow">Please listen carefully.</prosody>
      <break time="500ms"/>
      Your account balance is <say-as interpret-as="currency">$42.50</say-as>
    </speak>
  `,
};
```

--------------------------------

### Speak Action with Text in TypeScript

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk_activeTab=dependents

The Speak action instructs the AI Flow service to speak text to the user. This is a simple example of returning plain text as a response.

```typescript
interface SessionInfo {
  id: string;
  account_id: string;
  phone_number: string;
}

enum AiFlowActionType {
  SPEAK = "speak",
  AUDIO = "audio",
  HANGUP = "hangup"
}

interface AiFlowActionSpeak {
  type: "speak";
  session_id: string;
  text?: string;
  ssml?: string;
  tts?: any; // Simplified for example
  barge_in?: any; // Simplified for example
}

// Assuming 'event' is available from a previous handler like onUserSpeak
// return {
//   type: AiFlowActionType.SPEAK,
//   session_id: event.session.id,
//   text: "Hello, how can I help you?",
// };
```

--------------------------------

### AiFlowApiEventUserSpeak Interface

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk/v/1.0_activeTab=dependencies

Defines the structure of the `user_speak` event, containing the recognized speech text and session details. Includes an example handler for analyzing intent.

```typescript
interface AiFlowApiEventUserSpeak {
  type: "user_speak";
  text: string; // Recognized speech text
  session: {
    id: string;
    account_id: string;
    phone_number: string;
  };
}

// Example:
onUserSpeak: async (event) => {
  const intent = analyzeIntent(event.text);

  if (intent === "help") {
    return "I can help you with billing, support, or sales.";
  }

  return processUserInput(event.text);
};
```

--------------------------------

### Manually Process Event with AiFlowAssistant

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk/v/1.0_activeTab=dependencies

Provides an example of manually triggering an event processing using `assistant.onEvent()`, which is useful for custom integration scenarios.

```javascript
const action = await assistant.onEvent(event);
```

--------------------------------

### Audio Action with Barge-in Configuration in TypeScript

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk_activeTab=dependents

The Audio action allows playing pre-recorded audio files to the user. This example demonstrates playing a base64 encoded WAV file and configuring barge-in behavior.

```typescript
interface SessionInfo {
  id: string;
  account_id: string;
  phone_number: string;
}

enum AiFlowActionType {
  SPEAK = "speak",
  AUDIO = "audio",
  HANGUP = "hangup"
}

enum BargeInStrategy {
  MINIMUM_CHARACTERS = "minimum_characters"
}

interface BargeInConfig {
  strategy: BargeInStrategy;
  minimum_characters: number;
}

interface AiFlowActionAudio {
  type: "audio";
  session_id: string;
  audio: string; // Base64 encoded WAV (8kHz, mono, 16-bit)
  barge_in?: BargeInConfig;
}

// Assuming 'event' and 'base64EncodedWavData' are available
// return {
//   type: AiFlowActionType.AUDIO,
//   session_id: event.session.id,
//   audio: base64EncodedWavData,
//   barge_in: {
//     strategy: BargeInStrategy.MINIMUM_CHARACTERS,
//     minimum_characters: 3,
//   },
// };
```

--------------------------------

### Create Speak Action with SSML in TypeScript

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk/v/1.0_activeTab=code

This example demonstrates creating a 'speak' action using SSML for more advanced text-to-speech control, including prosody and pauses. It requires a session ID and the SSML markup.

```typescript
return {
  type: AiFlowActionType.SPEAK,
  session_id: event.session.id,
  ssml: `
    <speak>
      <prosody rate="slow">Please listen carefully.</prosody>
      <break time="500ms"/>
      Your account balance is <say-as interpret-as="currency">$42.50</say-as>
    </speak>
  `,
};
```

--------------------------------

### Handle UserSpeak Event in AI Flow SDK

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk/v/1.0_activeTab=versions

Defines the structure of a UserSpeak event and provides an example of an onUserSpeak handler that analyzes user text to determine intent and returns an appropriate response.

```typescript
interface AiFlowApiEventUserSpeak {
  type: "user_speak";
  text: string; // Recognized speech text
  session: {
    id: string;
    account_id: string;
    phone_number: string;
  };
}

onUserSpeak: async (event) => {
  const intent = analyzeIntent(event.text);

  if (intent === "help") {
    return "I can help you with billing, support, or sales.";
  }

  return processUserInput(event.text);
};
```

--------------------------------

### Handle Events and Construct Actions with Express

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk

This example shows how to set up an Express server to receive webhook events from the AI Flow SDK and construct appropriate actions in response. It handles various event types like 'session_start', 'user_speak', and 'session_end', demonstrating different action types such as SPEAK, GATHER_DTMF, TRANSFER, and HANGUP. Dependencies include 'express' and '@sipgate/ai-flow-sdk'.

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

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

app.post("/webhook", async (req, res) => {
  const event = req.body;

  let action = null;

  switch (event.type) {
    case "session_start":
      action = {
        type: AiFlowActionType.SPEAK,
        session_id: event.session.id,
        text: "Welcome to our service!",
        barge_in: {
          strategy: "minimum_characters",
          minimum_characters: 5,
        },
      };
      break;

    case "user_speak":
      if (event.text.toLowerCase().includes("menu")) {
        // Present IVR menu using DTMF gathering
        action = {
          type: AiFlowActionType.GATHER_DTMF,
          session_id: event.session.id,
          num_characters: 1,
          audio_url: "https://example.com/prompts/main-menu.wav",
          timeout_ms: 10000,
        };
      } else if (event.text.toLowerCase().includes("transfer")) {
        action = {
          type: AiFlowActionType.TRANSFER,
          session_id: event.session.id,
          target_phone_number: "+1234567890",
          caller_id_name: "Support",
          caller_id_number: "+1234567890",
        };
      } else if (event.text.toLowerCase().includes("goodbye")) {
        action = {
          type: AiFlowActionType.HANGUP,
          session_id: event.session.id,
        };
      } else {
        action = {
          type: AiFlowActionType.SPEAK,
          session_id: event.session.id,
          text: `You said: ${event.text}`,
        };
      }
      break;

    case "user_barge_in":
      console.log(`User interrupted with: ${event.text}`);
      action = {
        type: AiFlowActionType.SPEAK,
        session_id: event.session.id,
        text: "I'm listening, go ahead.",
      };
      break;

    case "assistant_speak":
      console.log(`Spoke for ${event.duration_ms}ms`);
      // Optional: track metrics, no action needed
      break;

    case "session_end":
      console.log(`Session ${event.session.id} ended`);
      // Cleanup logic, no action needed
      break;
  }

  // Return action if one was created
  if (action) {
    res.json(action);
  } else {
    res.status(204).send();
  }
});

app.listen(3000, () => {
  console.log("Webhook server listening on port 3000");
});
```

--------------------------------

### Speak Action with Custom TTS in TypeScript

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk_activeTab=dependents

This example shows how to configure a custom Text-to-Speech (TTS) provider for the Speak action, allowing for selection of different voices and languages.

```typescript
interface SessionInfo {
  id: string;
  account_id: string;
  phone_number: string;
}

enum AiFlowActionType {
  SPEAK = "speak",
  AUDIO = "audio",
  HANGUP = "hangup"
}

enum TtsProvider {
  AZURE = "azure"
}

interface TtsConfig {
  provider: TtsProvider;
  language: string;
  voice: string;
}

interface AiFlowActionSpeak {
  type: "speak";
  session_id: string;
  text?: string;
  ssml?: string;
  tts?: TtsConfig;
  barge_in?: any; // Simplified for example
}

// Assuming 'event' is available from a previous handler like onUserSpeak
// return {
//   type: AiFlowActionType.SPEAK,
//   session_id: event.session.id,
//   text: "Hello in a different voice",
//   tts: {
//     provider: TtsProvider.AZURE,
//     language: "en-US",
//     voice: "en-US-JennyNeural",
//   },
// };
```

--------------------------------

### Convert Audio to Base64 for AI Flow SDK

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk_activeTab=code

This example demonstrates how to read an audio file, convert it to a Base64 encoded string, and structure it for the AI Flow SDK's audio action. It assumes the audio file is already in the correct WAV format (8kHz, Mono, 16-bit PCM).

```javascript
import fs from "fs";

const audioBuffer = fs.readFileSync("audio.wav");
const base64Audio = audioBuffer.toString("base64");

return {
  type: AiFlowActionType.AUDIO,
  session_id: event.session.id,
  audio: base64Audio,
};

```

--------------------------------

### Handle UserSpeak Event in TypeScript

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk/v/1.0_activeTab=dependents

Provides an example of handling the 'user_speak' event. The handler analyzes the user's text input, determines intent, and returns an appropriate response or processes the input further.

```typescript
onUserSpeak: async (event) => {
  const intent = analyzeIntent(event.text);

  if (intent === "help") {
    return "I can help you with billing, support, or sales.";
  }

  return processUserInput(event.text);
};
```

--------------------------------

### Convert Audio to Base64 for AI Flow SDK (JavaScript)

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk

This example demonstrates how to read an audio file, convert it to a Base64 encoded string, and format it for use with the AI Flow SDK's audio action. Ensure the audio file adheres to WAV format, 8kHz sample rate, mono channels, 16-bit PCM, and Base64 encoding.

```javascript
import fs from "fs";

const audioBuffer = fs.readFileSync("audio.wav");
const base64Audio = audioBuffer.toString("base64");

return {
  type: AiFlowActionType.AUDIO,
  session_id: event.session.id,
  audio: base64Audio,
};
```

--------------------------------

### AI Flow SDK: Event Type Definitions (session_start, user_speak, assistant_speak)

Source: https://www.npmjs.com/package/@sipgate/ai-flow-sdk/package/%40sipgate/ai-flow-sdk_activeTab=code

TypeScript interfaces defining specific event types for session start, user speech recognition, and assistant speech completion. Includes details on recognized text, spoken text/SSML, and duration.

```typescript
// session_start
interface AiFlowEventSessionStart {
  type: "session_start";
  session: {
    id: string;
    account_id: string;
    phone_number: string; // Phone number for this flow session
    direction?: "inbound" | "outbound"; // Call direction
    from_phone_number: string;
    to_phone_number: string;
  };
}

// user_speak
interface AiFlowEventUserSpeak {
  type: "user_speak";
  text: string; // Recognized speech text
  session: SessionInfo;
}

// assistant_speak
interface AiFlowEventAssistantSpeak {
  type: "assistant_speak";
  text?: string; // Text that was spoken
  ssml?: string; // SSML that was used (if applicable)
  duration_ms: number; // Duration of speech in milliseconds
  speech_started_at: number; // Unix timestamp (ms) when speech started
  session: SessionInfo;
}
```
Tokens:
Raw