Make a call
Signature
X-VH-Caller-ID, X-VH-Record, and X-VH-DialUser are instructions for your Answer URL: Vobiz delivers them, and your VobizXML acts on them. The hosted Playground server used in demo mode handles all three for you.CallEvent.callId.
Throws
What happens next:
- The SDK opens the microphone (Android asks for permission the first time), prepares audio, and sends the call to Vobiz.
- Vobiz requests the Answer URL of the endpoint’s application, with the destination in
To. Your VobizXML decides what happens, usually a<Dial>to the number. callEventsreportsconnecting, thenringing, thenactivewhen the call is answered, andendedwhen it finishes.
Placing a call spends money on your Vobiz account. Test with your own numbers.
Caller ID
Carriers reach a phone only when the caller ID is a number your Vobiz account owns. Your Answer URL sets it with<Dial callerId="...">; pass callerId to makeCall if the app chooses the number, and read it from the X-VH-Caller-ID parameter on your server. A call without a valid caller ID fails, and callEvents reports failed with the SIP code.
Ringing and early media
When the far end sends183 Session Progress with audio, such as ringback or a carrier announcement, the SDK plays it before the call is answered and emits an EarlyMediaEvent on callMediaEvents.
If Vobiz sends no response at all within 30 seconds, the call ends with reason setup_timeout. Once the destination is ringing, the call keeps ringing until it is answered, declined, or times out on the Vobiz side.
Receive a call
A call rings the app when:- your application’s VobizXML rings the endpoint with
<Dial><User>sip:YOUR_SIP_USERNAME@registrar.vobiz.ai</User></Dial>, or - you place a call to
sip:YOUR_SIP_USERNAME@registrar.vobiz.aiwith the Voice API.
callEvents emits a CallEvent with state: CallStateStatus.incoming.
While a call is in progress, a second incoming call is declined with
486 Busy Here: the caller hears busy and the app isn’t disturbed.
Answer
Signature
callId defaults to the current call. It does nothing unless the call is incoming. The state moves to connecting (“Answering”), then active.
If answering fails, the SDK declines the call so the caller isn’t left ringing: 480 when the microphone can’t be opened, 488 when the offer has no usable audio, and 500 otherwise. errorEvents emits answer_failed.
Decline
Signature
486 Busy Here: the caller hears busy. On a call that is already answered, it hangs up instead.
Caller cancelled.
Hang up
Signature
CANCEL), an incoming call that is still ringing is declined, and an answered call gets a BYE. Both sides see the call end. callId defaults to the current call; with no call, it does nothing.
BYE or CANCEL again once it reconnects, so the other side isn’t left on a silent call. See Network and reconnection.
Call states
CallEvent.state is a CallStateStatus:
Outbound sequence:
connecting > ringing > active > (held > active) > ended.
Inbound sequence: incoming > connecting > active > ended.
During a network drop, the SDK re-emits the current state with reason set to reconnecting, then reconnected when the call recovers.
Why a call ended
CallEvent
The client also exposes the current call’s state directly:
callState, currentCallId, callDirection, callUuid, lastCallUuid (the previous call’s, for recordings), and callHeaders.