Skip to main content

Mobile SDK Workflows

Events and States​

This document describes what call states and events are expected when making an outgoing call using the Cloudonix Mobile SDK. When using the Cloudonix Registration-Free workflow, all calls (even those in response to an "incoming call notification") behave as an outgoing call, in that regard.

In the following detail descriptions, the following categories are used:

  • API Call : the application initiated an API call to the Cloudonix Mobile SDK.
  • Call State Event: The Cloudonix Mobile SDK has sent a call progress report to the application's onCallState event handler.
  • SIP Message Sent: The Cloudonix Mobile SDK has sent a SIP message to the Cloudonix Platform (this can be seen in the Cloudonix Mobile SDK logs, as delivered to the application using the onLog event).
  • SIP Message Received: The Cloudonix Mobile SDK has received a SIP message from the Cloudonix Platform (as can be seen in the Cloudonix Mobile SDK logs, as delivered to the application using the onLog event).

Outgoing Call Starting​

  1. API Call: CloudonixSDKClient::dial() (or any of the other dial* API calls, or the pickupRegistrationFreeCall API call) - the application submits a dial request to the Cloudonix Mobile SDK.
  2. Call State Event: CALL_STATE_STARTING - the Cloudonix Mobile SDK had accepted the dial request and assigned a "call key" to this request. The call may still immediately fail after it had "started" if the dial details are invalid or it the Cloudonix Mobile SDK is not in a valid state to start a call.
  3. SIP Message Sent: INVITE - the Cloudonix Mobile SDK connects to the Cloudonix Platform and tries to set up the call.
  4. Call State Event: CALL_STATE_CALLING - the Cloudonix Mobile SDK had successfully sent the first SIP message to the Cloudonix Platform and had yet to encounter any errors. When using TCP or TLS protocols, this means that the connection to the Cloudnix Platform was successfully created.
  5. SIP Message Received: 100 Your call is important to us, please wait while we route your call - the Cloudonix Platform had accepted the connection and is working on setting up the call.
  6. SIP Message Received: 100 trying -- your call is important to us - the Cloudonix Platform has accepted the call and started executing the customer's CXML Voice Application (this is often just a "call routing" application).
  7. SIP Message Received: 180 Ringing - The Cloudonix Platform has received the customer's CXML Voice Application and the Cloudonix Voice Application Runtime that is executing it.
  8. Call State Event: CALL_STATE_RINGING - the Cloudonix Mobile SDK notifies the application that the call is progressing. at this point the application may choose to generate a local "dialing" ringtone to notify the user of the progress, or use a visual indication. Depending on the CXML Voice Application, this state may be very short-lived so it may not be worth the effort of this indication.
  9. SIP Message Received: 183 Session Progress - The customer's CXML voice application has either issued its own "dialling ringtone" or dialed to a destination that issued such a ringtone. In case of an "internal dial" (from a Cloudonix Platform subscriber to another Cloudonix Platform subscriber), the Cloudonix Platform will generate the "dialling ringtone" itself at this point.
  10. Call State Event: CALL_STATE_EARLY - the Cloudonix Mobile SDK notifies the application that the call is progressing and the remote side is now playing audio to either simulate a ringing or a "pre-answer" announcement (aka "early media") such as a voice mail routing message. If the application had generated a local progress tone - it should now stop that tone.

Outgoing Call Is Answered​

Continued from Outgoing Call Starting.

  1. SIP Message Received: 200 OK - the CXML Voice Application has answered the call, or - in case of a dial to a remote destination - the callee has answered.
  2. Call State Event: CALL_STATE_CONFIRMED - the Cloudonix Mobile SDK notifies the application that the call is connected and the application should now to have bi-directional audio with the remote callee.
  3. SIP Message Sent: ACK - the Cloudonix Mobile SDK confirms to the Cloudonix Platform that the call is connected.

During the call, the following SIP messages may be sent by the Cloudonix Mobile SDK: OPTIONS or NOTIFY and in response the Cloudonix Platform would respond with a 200 OK SIP response.

Caller Cancelling (hanging up before the call was answered)​

Continued from Outgoing Call Starting.

  1. API Call: CloudonixSDKClient::hangup() (or any other hangup* API calls) - the application requests the call to be aborted.
  2. SIP Message Sent: CANCEL - the Cloudonix Mobile SDK is notifying the Cloudonix Platform that a call that had not been connected yet should be aborted.
  3. Call State Event: CALL_STATE_DISCONNECTED - the Cloudonix Mobile SDK notifies the application that the call had been aborted.
  4. SIP Message Received: 200 CANCELLING - the Cloudonix Platform approves that it received the request to abort the call.
  5. SIP Message Received: 487 Request Terminated - the Cloudonix Platform notifies that the call that has not yet connected had been aborted.
  6. SIP Message Sent: ACK - the Cloudonix Mobile SDK acknowledges the termination of the call.

Caller hanging up (after the call was answered)​

Continued from Outgoing Call Is Answered.

  1. API Call: CloudonixSDKClient::hangup() (or any other hangup* API calls) - the application requests the call to be aborted.
  2. SIP Message Sent: BYE - the Cloudonix Mobile SDK notifies the Cloudonix Platform that the caller is hanging up the call.
  3. Call State Event: CALL_STATE_DISCONNECTED - the Cloudonix Mobile SDK notifies the application that it disconnected the call.
  4. _SIP Message Received: 200 OK - the Cloudonix Platform accepts the disconnect.

Callee rejecting the call (before answering)​

Continued from Outgoing Call Starting (either before or after CALL_STATE_EARLY).

  1. SIP Message Received: 603 Declined - the Cloudonix Platform notifies that the call recipient had declined to accept the call, either actively or the ringing timeout has expired.
  2. Call State Event: CALL_STATE_DISCONNECTED - the Cloudonix Mobile SDK notifies the application that the call has been disconnected.
  3. SIP Message Sent: ACK - the Cloudonix Mobile SDK acknowledges the termination of the call.

Callee hanging up (after answering)​

Continue from Outgoing Call Is Answered.

  1. SIP Message Received: BYE - the Cloudonix Platform notifies that the callee has hanged up the call.
  2. Call State Event: CALL_STATE_DISCONNECTED - the Cloudonix Mobile SDK notifies the application that the call was disconnected.
  3. SIP Message Sent: 200 Ok - the Cloudonix Mobile SDK accepts the disconnect.