Architecture
commonvoice separates your application authentication from voice transport. Your backend authenticates an existing user and requests a short-lived voice session using a project secret. The client connects to our signaling endpoint and uses WebRTC for peer-to-peer audio.
WebRTC media traffic flows between peers (or through TURN when configured). The API handles authorization and signaling, not audio recording or a full conferencing SFU in this MVP.
Developer registration
Submit the developer access form. Valid email syntax, disposable-domain blocklist and country-aware mobile-number checks are applied; an email confirmation link expires after 30 minutes. Approval remains manual. Phone ownership is not verified.
POST /api/v1/developers/register
Content-Type: application/json
{
"name": "Example Developer",
"email": "developer@example.com",
"phone": "+919876543210",
"application": "Worker Portal",
"platform": "android",
"details": "Voice calling for authenticated workers.",
"accept_terms": true
}Project credentials
Approval issues a project_id and project_secret. Keep these on your application backend, never in an Android APK, an iOS bundle, or web JavaScript. For the MVP, an authenticated administrator approves requests through protected administrative API endpoints.
Create a user session
After your own server authenticates the user and verifies the user is authorized for the target room, it calls:
POST /api/v1/sessions
X-Project-ID: cv_your_project
X-Project-Secret: YOUR_SERVER_ONLY_SECRET
Content-Type: application/json
{
"user_id": "worker_42",
"room_id": "job_118",
"display_name": "Rahul Kumar"
}The response includes a 15-minute signed access_token scoped to a single project, user and room. Room IDs must be generated and authorized by the integrating backend; never trust a user's arbitrary room selection.
Signaling protocol
Connect to wss://YOUR_HOST/api/v1/signal?token=... in production. Messages: ready, peer-joined, offer, answer, ice, peer-left, leave. The MVP supports two concurrent participants per room. Use HTTPS/WSS in production. The voice stream itself uses WebRTC and requires a TURN server for reliable calling on restrictive networks.
Web integration
A browser SDK starter is included at /sdk/commonvoice-web.js in the source repository, along with a demo page. The demo requires valid short-lived session tokens issued by your trusted backend.
import { CommonVoiceClient } from './commonvoice-web.js';
const client = new CommonVoiceClient({
endpoint: 'wss://YOUR_HOST/api/v1/signal',
token: userSession.access_token,
onState: console.log
});
await client.connect();
await client.startCall();Native mobile integration
Android and iOS are the strategic priority. A full native SDK will need audio routing, phone interruption handling, native call UI, background notifications, TURN configuration, and release testing. Native Android and iOS SDKs are not yet implemented in this MVP.
Security checklist
- Authenticate the existing application user on your backend.
- Authorize both participants against the exact requested room.
- Never disclose project secrets to mobile or browser clients.
- Set a strong signing secret and administrative key.
- Use an approved SMTP provider for email ownership confirmation.
- Set exact
COMMONVOICE_ALLOWED_ORIGINSfor browser signaling. - Deploy HTTPS/WSS, configure TURN credentials and protect against abuse.
- Use distributed signaling and database-backed rate limiting before scaling beyond one worker.
Registration limits
| Field | Maximum |
|---|---|
| Name | 80 characters |
| 254 characters | |
| Mobile | 15 digits + leading + |
| Application name | 100 characters |
| Use case | 500 characters |
| JSON request body | 12 KB (content-length guard; production proxy should also cap streamed bodies) |