Skip to main content
This page covers placing a call, answering and declining incoming calls, hanging up, and the states every call goes through. The client handles one call at a time.

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.
Returns the SDK’s ID for the call. Use it to match CallEvent.callId. Throws What happens next:
  1. The SDK opens the microphone (Android asks for permission the first time), prepares audio, and sends the call to Vobiz.
  2. 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.
  3. callEvents reports connecting, then ringing, then active when the call is answered, and ended when 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 sends 183 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.ai with the Voice API.
The client must be signed in and registered (on Android with the app closed, see Push notifications). When the call arrives, 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
Answers the ringing call. 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
Declines a ringing call with 486 Busy Here: the caller hears busy. On a call that is already answered, it hangs up instead.
If the caller hangs up before you answer, the call ends with the reason Caller cancelled.

Hang up

Signature
Ends the call. A ringing outbound call is cancelled (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.
If the network is down when you hang up, the SDK sends the 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.

Next steps