Skip to main content

Getting Started

Welcome to SFVoPI (Superfone Voice over Programmable Interface) — a programmable voice API that gives your AI agents a real phone presence — with built-in handoff to your human team.

SFVoPI is the API layer of the Superfone Voice 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, customer support automation, AI-powered sales outreach, 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.

  • India: 10-digit Indian mobile numbers — with 2-3x better pickup rates vs landline.
  • US, Canada & other markets: local (geographic), toll-free, national, and mobile numbers — depending on what's available in the country.

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 — Write to hello@superfone.in to get API access and a test account.
  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?