How to Use the Vonage Client SDK for In-App Voice Calling

Objective

Use the Vonage Client SDK to embed real-time voice calling into your iOS, Android, or JavaScript (Web) application. This article covers how to set up a session, make and receive calls, and use audio controls and push notifications.

Applies To

• Vonage Client SDK
• Voice API
• iOS
• Android
• JavaScript (Web)

Procedure

Step 1 – Set Up an Authenticated Session

Before making or receiving calls, establish an authenticated session using a JSON Web Token (JWT) minted by your custom backend.

1. Generate a JWT on your backend using your Vonage application private key. The JWT must include the following claims: sub, application_id, acl, and exp.
2. Pass the JWT to the SDK to create a session:

client.createSession(jwt)

Note: Session lifetime is set by the JWT's exp claim (30s–24h, backend-controlled; defaults to 15 min only if unset). The SDK has no fixed TTL. Use refreshSession(jwt) to extend before expiry.

Step 2 – Receive Inbound Calls (Phone-to-App)

To receive inbound voice calls in your app, listen for the callInvite event and call client.answer() to accept it.

client.on("callInvite", (callId, from, type) => {

  client.answer(callId)

})

The from field identifies the caller. The type field indicates the channel — for example, phone for Public Switched Telephone Network (PSTN) calls or app for in-app calls.

Step 3 – Make Outbound Calls (App-to-Phone)

To initiate an outbound call to a phone number, use the serverCall() method. This sends a context object to the Vonage API, which then contacts your backend's answer webhook to retrieve Nexmo Call Control Object (NCCO) routing instructions.

client.serverCall({ context: "my-call-context" })

Step 4 – Set Up Push Notifications

To ensure users receive incoming calls even when the app is in the background or terminated, register a push token with the SDK.

iOS — Uses Apple's PushKit (VoIP push) via Apple Push Notification service (APNs). A valid push certificate must be uploaded to the Vonage Dashboard.

client.registerVoipToken(token, isSandbox)

Note: On iOS, every VoIP push handled via PushKit must result in a reportNewIncomingCall to CallKit, as required by Apple.

Android — Uses Firebase Cloud Messaging (FCM) to deliver inbound call payloads.

client.registerDevicePushToken(token)

Step 5 – Use Audio Controls During a Call

The SDK provides the following audio controls during an active call:

Step 6 – Send DTMF Tones

To send Dual-Tone Multi-Frequency (DTMF) tones during an active call — for example, to navigate an Interactive Voice Response (IVR) menu or enter a verification code — use sendDTMF().

client.sendDTMF(callId, "1234")

Step 7 – Set Up Conference Calls

To connect multiple participants into a single conversation, use server-managed call flows. Your backend controls the conference room logic via NCCO instructions. Participants join using serverCall() with a shared context value.

client.serverCall({ context: "conference-room-1" })

Additional Capabilities

The SDK also supports the following features. For full implementation details, see the Vonage Client SDK Guides.

• Call Transfer — Transfer an active call to another participant or number.
• Call Hold — Place an active call on hold and resume it later.
• Reconnection — Automatically re-establish a call after a network interruption using Interactive Connectivity Establishment (ICE).
• Call Quality Monitoring — The SDK reports Mean Opinion Score (MOS) via onRTCStatsUpdate to help monitor voice quality in real time (scale: 1.0 = poor, 5.0 = excellent).

Platform Guide Availability

Additional Information

• Vonage Client SDK Guides
• Vonage Client SDK API Reference
• In-App Calling – Voice API Concepts
• Session Failed Due to a Timeout Expiration
• Outbound In-App Voice Calls Fail to Complete
• How to Fix Device Registration Failure Due to Max Devices Limit
• For further assistance, submit a Support request.