API Reference

Welcome to the sipgate AI Flow API documentation. This documentation is language-agnostic and describes the HTTP and WebSocket protocols that power the AI Flow service.

Overview

sipgate AI Flow is a voice assistant platform that uses an event-driven architecture. Your application receives events (like when a user speaks) and responds with actions (like speaking text back to the user).

Architecture

Integration Methods

HTTP Webhooks

Receive events via HTTP POST requests to your webhook endpoint.

Best for:

• Serverless functions (AWS Lambda, Google Cloud Functions)
• REST APIs
• Simple integrations

Learn more →

WebSocket

Maintain a persistent WebSocket connection for real-time event streaming.

Best for:

• Real-time applications
• Lower latency requirements
• High-volume scenarios

Learn more →

Event-Driven Flow

Core Concepts

Events

Events are JSON objects sent from the AI Flow service to your application:

• session_start - When a call begins
• user_speak - When the user speaks (includes barged_in flag if user interrupted)
• assistant_speak - After your assistant speaks
• session_end - When the call ends

View all events →

Actions

Actions are JSON objects you send back to the AI Flow service:

• speak - Speak text or SSML
• audio - Play pre-recorded audio
• hangup - End the call
• transfer - Transfer to another number

View all actions →

Quick Example

Here's a minimal example using HTTP webhooks:

1. Receive an event:

POST /webhook
Content-Type: application/json

{
  "type": "user_speak",
  "text": "Hello",
  "session": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "account_id": "account-123",
    "phone_number": "+1234567890",
    "from_phone_number": "+9876543210",
    "to_phone_number": "+1234567890"
  }
}

2. Respond with an action:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "type": "speak",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "text": "Hello! How can I help you?"
}

Language Support

This API works with any programming language that can:

• Receive HTTP requests (for webhooks)
• Receive WebSocket connections (for real-time)
• Parse and generate JSON (for events and actions)

Examples are provided in multiple languages throughout the documentation.

Next Steps

• Quick Start - Build your first integration
• HTTP Webhooks - Set up HTTP integration
• WebSocket - Set up WebSocket integration
• Event Types - Complete event reference
• Action Types - Complete action reference

TypeScript SDK

If you're using TypeScript, check out our TypeScript SDK documentation for a more convenient wrapper around this API.

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.