Troubleshooting

Common issues and solutions.

Common Issues

WebSocket Connection Errors

If you encounter WebSocket connection issues:

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

  ws.on("close", (code, reason) => {
    console.log(`Connection closed: ${code} - ${reason}`);
  });

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

Common causes:

• Network connectivity issues
• Firewall blocking WebSocket connections
• Incorrect WebSocket URL or protocol

Event Validation Errors

Use Zod schemas to validate incoming events:

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

app.post("/webhook", async (req, res) => {
  try {
    const event = AiFlowEventSchema.parse(req.body);
    const action = await assistant.onEvent(event);
    if (action) {
      res.json(action);
    } else {
      res.status(204).send();
    }
  } catch (error) {
    console.error("Invalid event:", error);
    res.status(400).json({ error: "Invalid event format" });
  }
});

Debug Mode

Enable debug logging to see all events and actions:

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

Audio Format Issues

When using the audio action, ensure your audio is in the correct format:

• Format: WAV
• Sample Rate: 16kHz
• Channels: Mono
• Bit Depth: 16-bit PCM
• Encoding: Base64

// Example: Convert audio file to correct format
import fs from "fs";

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

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

TypeScript Issues

Type Errors

Make sure you're importing types correctly:

import type {
  AiFlowEventUserSpeak,
  AiFlowAction,
} from "@sipgate/ai-flow-sdk";

Module Resolution

If you encounter module resolution errors, check your tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

Performance Issues

Slow Response Times

• Check your event handler performance
• Use async/await properly
• Avoid blocking operations
• Consider caching for frequently accessed data

Memory Leaks

• Clean up session state in onSessionEnd
• Remove event listeners
• Clear timers and intervals

Integration Issues

Express Middleware

If the Express middleware isn't working:

// Make sure express.json() is used
app.use(express.json());

// Check the route order
app.post("/webhook", assistant.express());

WebSocket Handler

If WebSocket messages aren't being processed:

// Ensure message handler is set up correctly
ws.on("message", assistant.ws(ws));

// Check message format
ws.on("message", (data) => {
  console.log("Received:", data.toString());
  assistant.ws(ws)(data);
});

Next Steps

• API Reference - Complete API documentation
• Examples - More examples and use cases