Skip to content

Connectivity Report ​

Tests whether this device and its network can carry a call, and reports why not.

It places a short real test call over the exact route a call takes: HTTPS to your region, the session's signalling connection, and a WebRTC connection to Vonage's media server carrying real microphone audio, whose quality is then measured for a few seconds. Nothing rings, and the test leg is hung up as soon as the test ends.

Because it uses the production route rather than a separate test server, a pass means calls from this device and network will connect, and a failure names the step that broke.

Signature ​

// Callback version
fun connectivityReport(
  options: ConnectivityReportOptions,
  callback: (Exception?, ConnectivityReport?) -> Unit
)

// Suspend version
suspend fun connectivityReport(
  options: ConnectivityReportOptions = ConnectivityReportOptions()
): ConnectivityReport

fun cancelConnectivityReport()

Parameters ​

PropertyTypeDefaultDescription
sampleDurationMsnumber12000How long real audio flows once media connects (3000–60000)
connectTimeoutMsnumber10000How long to wait for media to connect (1000–60000)

Return Type ​

A ConnectivityReport. Its JSON form (toJson() on Android, json on iOS, the object itself on JS) is versioned by schemaVersion and is what to send to Vonage support. Absent fields mean "not measured".

PropertyDescription
verdictpass, warn or fail
failedAtThe first stage that failed, see below
issuesFindings, each with a stable code, a severity, the stage and a hint saying what to do
environmentSDK version, OS, device model, network type (wifi, cellular, +vpn…), configured hosts
sessionSession id, user, connection state, reconnect attempts and the last failure
httpsReachability of the configured region over HTTPS, with its duration
microphonePermission; capturing, whether the microphone delivered audio; heardSound, whether that audio was louder than silence
mediaThe test leg id, the media server's address, codec, ICE candidate counts and setup timings
qualityMin/avg/max round-trip time, jitter, loss (both directions) and estimated MOS, totals, and one sample per second

Stages ​

StageMeaning
httpsVonage could not be reached over HTTPS
sessionThere is no usable session
microphoneThe microphone could not be opened, or delivered no audio
media.offerThe device could not set up its audio
media.legVonage did not create the test call's audio connection
media.noAnswerThe media server's answer could not be applied
media.gatheringThe device found no network path to send audio on
media.checkingAudio could not reach the media server: UDP is blocked
media.dtlsA path was found but the secure audio handshake failed
qualityAudio flowed, but with problems: no audio received, dropped, high delay, jitter or loss

Usage Example ​

try {
    val report = client.connectivityReport()
    if (report.verdict != ConnectivityVerdict.Pass) {
        println("Failed at: ${report.failedAt}")
        report.issues.forEach { println("${it.code}: ${it.hint}") }
    }
    // The JSON form is what to send to Vonage support.
    val forSupport = report.toJson()
}
catch(e: VGError) { /* The test could not run, e.g. a call is in progress */ }

Errors ​

The callback receives an error only when the test could not run at all. Every check that ran, failures included, is in the report.

Error TypeError CodeDescription
INTERNAL_ERRORdiagnostics:error:in_progressA connectivity report is already running
INTERNAL_ERRORdiagnostics:error:call_in_progressA call is in progress
INTERNAL_ERRORdiagnostics:error:cancelledcancelConnectivityReport was called
INTERNAL_ERRORdiagnostics:error:interrupted_by_callA call started during the test
INTERNAL_ERRORinternal:error:illegal_argument_exceptionAn option is out of range

For complete error reference and handling guidelines, see Error Reference.

Notes ​

  • Needs a session. Without one, the report contains the HTTPS and session checks and skips media.
  • It uses the microphone like a call does, so it may prompt for microphone permission. Ask the user to speak while it runs: silence never fails the test, but microphone.heardSound then stays false and says nothing about whether the microphone picks up sound.
  • The test leg is a real media leg of about the sample duration, and may be billed as a few seconds of in-app voice.
  • Media goes directly to Vonage's media servers over UDP; there is no TCP or TLS relay. When UDP is blocked the report says so: allow outbound UDP 10000–20000 to 216.147.0.0/18 and 168.100.64.0/18.
  • No IP address of the device is included. Support can find everything about the test from its media.legId and session.sessionId.

Built with VitePress.