Skip to main content

Getting Started

Welcome to SFVoPI (Superfone Voice over Programmable Interface) — a powerful programmable voice API that lets you build voice applications with ease. Think of it as Twilio Voice for the Superfone platform.

What is SFVoPI?​

SFVoPI enables you to:

  • Make and receive phone calls programmatically via REST API
  • Control call flow using webhooks and real-time events
  • Stream audio in real-time over WebSocket for AI voice agents, transcription, or custom audio processing
  • Manage VoIP numbers and link them to your applications

Whether you're building an AI voice assistant, IVR system, call center solution, or any voice-enabled application, SFVoPI provides the building blocks you need.

Key Concepts​

Apps​

An App is a container for your voice application logic. Each app has:

  • Webhook URLs that Superfone calls when events occur (incoming call, call answered, call ended)
  • HTTP methods (GET or POST) for webhook delivery
  • Fallback URLs for redundancy if primary webhooks fail

Apps define how calls should be handled when they arrive.

Numbers​

Numbers are VoIP phone numbers that you link to your apps. When someone calls a number linked to your app, Superfone triggers your app's webhook URLs to determine what happens next.

  • Numbers use E.164 format (e.g., +918000000001)
  • Each number can be linked to one app at a time
  • You can link multiple numbers to the same app

Calls​

Calls represent active or completed phone call sessions. You can:

  • Initiate outbound calls via API
  • Receive inbound calls on your linked numbers
  • Track call status (ringing, in-progress, completed, failed)
  • Access call metadata (duration, timestamps, hangup cause)

Webhooks​

Webhooks are HTTP callbacks that Superfone sends to your server when call events occur:

  • Answer webhook — Triggered when a call is answered (inbound or outbound)
  • Hangup webhook — Triggered when a call ends

Your webhook endpoints return JSON instructions telling Superfone what to do next (e.g., stream audio, play message, hang up).

Audio Streaming​

Audio Streaming lets you receive and send real-time audio over WebSocket during active calls. Use cases include:

  • AI voice agents (speech-to-text, LLM processing, text-to-speech)
  • Live transcription and sentiment analysis
  • Custom audio processing (noise reduction, voice effects)

Streams support multiple codecs (PCMU, PCMA) and sample rates (8kHz, 16kHz).

Architecture Overview​

Here's how SFVoPI fits into your application:

Flow:

  1. Your server creates an app via REST API with webhook URLs
  2. You link a VoIP number to the app
  3. When a call arrives, Superfone sends an HTTP request to your answer webhook
  4. Your webhook responds with instructions (e.g., "stream audio to this WebSocket URL")
  5. Superfone establishes a WebSocket connection and streams audio bidirectionally
  6. When the call ends, Superfone sends an HTTP request to your hangup webhook

Prerequisites​

Before you start building with SFVoPI, you'll need:

  1. API Key — Contact the Superfone team to get your API key (self-service provisioning coming soon)
  2. Publicly accessible server — Your webhook URLs must be reachable from the internet
  3. Basic understanding of webhooks — Familiarity with HTTP callbacks and request/response patterns
  4. WebSocket knowledge (optional) — Required only if you plan to use audio streaming

Next Steps​

Ready to build your first voice application?

Support​

Need help? Have questions?