Voice Calling APIs: How to Add Audio Calls to an App

A voice calling API lets your app place and receive audio calls without building telephony or real-time media handling from scratch. This guide covers the general steps for adding calls to a web or mobile app. Exact SDK names, settings and features differ between providers, so check each step against your provider's own documentation.

Before you start

First decide which kind of call you need. App-to-app calls carry audio between users of your app over the internet. App-to-phone and phone-to-app calls connect to the regular phone network and usually require phone numbers from a provider. Some services support both, and some support only one.

Audio capture and playback run locally on each user's device. Calling itself almost always depends on a hosted service: something has to connect the two parties, relay media when a direct connection fails, and bridge to the phone network if you use it. Even a self-hosted setup built on open real-time media standards still needs your own signaling server and, in practice, a relay server.

• An account and project with your chosen provider, plus its API credentials
• A server-side component you control, so secret credentials never ship inside the client app
• A way to authenticate your own users before they can start a call
• A secure (HTTPS) origin for web apps, because browsers only allow microphone access in a secure context
• Microphone permission handling on every platform you support
• A clear policy on call recording and data retention, if you plan to record

Step-by-step instructions

Work in a test or sandbox project if your provider offers one, and put calling behind a feature flag. That keeps the change reversible: you can switch calling off without redeploying the rest of the app.

• 1. Store the provider's credentials as server-side environment variables or in a secrets manager, not in client code or a repository.
• 2. Add a server endpoint that checks the signed-in user and returns a short-lived token or session credential for the calling SDK. Many providers use this pattern; follow the token format your provider specifies.
• 3. Install the provider's client SDK, or use the platform's real-time media APIs directly if you are building your own app-to-app calling.
• 4. Ask for microphone permission when the user starts or answers a call, not when the app opens. Show a clear message if permission is denied and explain how to grant it again.
• 5. List available input devices and let users choose a microphone. Where the platform allows it, also let them choose the output device. Not every browser lets a web page pick the output device, so provide a fallback.
• 6. Review the audio processing options: echo cancellation, noise suppression and automatic gain control. Check which ones your SDK enables by default before changing them, because turning them off often brings back echo or background noise.
• 7. Handle call states in the interface: connecting, ringing, connected, on hold or muted, ended and failed. Give users a visible mute control and an input level indicator.
• 8. For phone network calls, configure the webhook or callback address the provider calls when a call arrives or changes state. Your server responds with instructions for that call, such as connecting it to a user.
• 9. For app-to-app calls, make sure a relay (TURN) server is configured. Without one, calls between users on restrictive networks may fail or carry audio in only one direction.
• 10. When a call ends, release the microphone by stopping the capture tracks, so the system recording indicator turns off.

SDK major versions sometimes rename methods or change default settings. Pin the version you tested with and read the migration notes before upgrading.

Check the output

Test with two real devices on different networks, for example one on Wi-Fi and one on mobile data. A call that only works when both devices share a network often points to a missing or misconfigured relay.

• Both sides hear each other clearly, with no one-way audio
• The input level indicator moves when the user speaks and stays low in silence
• Mute stops audio on the other side, and unmute restores it
• The selected input device and output device are actually the ones being used
• No echo when one side uses speakers instead of headphones
• The system microphone indicator turns off after the call ends
• Incoming calls ring and can be answered when the app is in the background, if your platform and SDK support that

For web apps, connection statistics from the real-time media API can show packet loss, jitter and round-trip time during a call. Many SDKs also expose their own quality events. Keep in mind that calls to the regular phone network typically carry lower-fidelity audio than app-to-app calls, so compare each call type against its own expectations. The sample rate and codec are usually negotiated automatically; check what your SDK reports rather than assuming a value.

If you record calls, confirm where recordings are stored, how long the provider keeps them and who can access them. Verify this in your provider's terms and account settings rather than relying on defaults, and tell callers when a call is recorded where the law requires it.

Common problems and next steps

Microphone works locally but not after deployment: web apps need HTTPS for microphone access. Check that the production site is served securely and that no embedded frame is blocking microphone permission.

One-way audio or calls that never connect: this usually comes from network address translation or firewalls. Confirm that a relay server is configured and reachable, and that the token or configuration passed to the client includes it.

Wrong microphone or speaker: the system default may not be the device the user expects, especially after plugging in a headset. Re-read the device list when devices change and let users switch during a call.

Low input level or distorted audio: check the system input level and the gain settings for the chosen microphone. If automatic gain control is on, avoid stacking it with manual boosting.

Echo or background noise: make sure echo cancellation and noise suppression are enabled, and suggest headphones for users on speakers. Some Bluetooth headsets switch to a lower-quality mode when their microphone is active, which can make calls sound worse than music playback.

Incoming phone calls never reach your app: the provider must be able to reach your webhook address from the internet. Check the provider's request logs or debugger, if available, and confirm your server returns a valid response quickly.

Calls drop after a fixed time or fail to start for some users: access tokens may be expiring. Refresh tokens before they run out and log token errors on the server.

Once basic calls work, consider next steps such as call quality reporting, reconnection after brief network loss, and limits on who can call whom to prevent abuse and unexpected charges.