Appearance

API Reference ​

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

Overview ​

sipgate 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 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 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:

json
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:

json
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 ​

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? We publish two auto-generated files following the llms.txt spec:

  • /llms.txt — short index, auto-discovered by AI tooling.
  • /llms-full.txt — full documentation corpus in a single file, ideal for pasting into an LLM context.