Skip to main content

Registration Free Dialing

The Registration-Free Dialing (aka: RegFree Dialing) protocol for Cloudonix allows mobile user agents to make and receive calls without maintaining a costly (in power and data) SIP registration.

Instead the application relies on a server application to handle call setup for the mobile application and notify the application of incoming calls using mobile push notifications.

The use of an application-specific server also allows to dispense with the slow and insecure SIP user/password authentication mechanism and rely on the application-specific authorization mechanism that likely already exists between the mobile application and its server.

Architecture​

Traditional SIP services require each device to be registered at all times by sending periodic REGISTER messages. The Cloudonix platform supports both the traditional SIP registration scheme but also supports using pre-authenticated bearer tokens or just-in-time call authorization.

Outbound calls performed using the RegFree dialing policy are negotiated between the custom application’s server and the Cloudonix API before the actual SIP session is initiated - this allows the server application to negotiate an authorization token on behalf of the mobile user agent. When the mobile user agent initiates the SIP session it authenticates with the Cloudonix subscriber gateway using that authorization token. The authorization token can be a more secure per-call one-time authorization token, or a per-subscriber long-term authorization token.

The process for inbound calls is similar except that the process will be initiated by the Cloudonix platform: when a call is received the Cloudonix platform will send an "incoming call notification" to the customer's server application to notify it of the incoming call and provide the call authorization token. The server application can then send signal the application, using mobile push notification. The mobile user agent can "pick up the call" by dialing using the incoming call authorization token.

Workflows​

Call Initiation​

Diagram​

In Detail​

  1. Subscriber’s application (mobile user agent) initiates call through the customer's server application.
  2. Customer's server application calls Cloudonix API Call Management Service’s Session Initiation method, to receive a new session token. The server application can submit - in the same call or as using a Session Update call - a custom routing scenario for just the current call.
  3. Server application passes the session token to the subscriber’s application.
  4. Subscriber’s application initializes the Cloudonix Mobile SDK with the subscriber’s account details (MSISDN and domain) and stars a call using the dialRegistrationFree() API.
  • If the application uses a third-party SIP SDK instead of the Cloudonix Mobile SDK, a RegFree call can be started by adding the following headers to the INVITE message:
  • X-Cloudonix-Session - set to the session token from the Cloudonix Session Initiation response.
  • X-Cloudonix-Domain - set to the Cloudonix domain for the subscriber.
  1. Cloudonix Subscriber Gateway intercepts the dial and validates the session token. If the token is invalid, the call is rejected as if a SIP authentication has failed.
  2. Cloudonix Voice Application Server receives the call normally and uses the pre-set session to route the call normally.

Call Reception​

Diagram​

In Detail​

  1. A call is received on the Cloudonix Voice Application Server, and handled normally by the voice application logic. The voice application routes the call to a subscriber.
  2. Call routing logic verifies that the destination number is for a valid subscriber and checks if the subscriber has an active SIP registration. If the subscriber does not have an active SIP registration and the domain has a RegFree Control Endpoint configured, the Cloudonix platform sends a RegFree Incoming Call Notification to the configured RegFree Control Endpoint.
  3. Customer's server application receives the RegFree Incoming Call Notification and sends a mobile push notification, to the subscriber's application, containing the notification details.
  4. Subscriber' application starts an HTTP long poll GET request on the Session Control - Ringing Notification using the Cloudonix API server address, the receiving subscriber's MSISDN, and session token provided in the incoming call notification.
  5. Subscriber’s application simulates an incoming call (ringing, etc) and waits for the user to answer the incoming call.
  6. When the user indicates they want to answer the call, Subscriber’s application initializes the Cloudonix Mobile SDK with the subscriber’s account details (MSISDN and domain) and picks up the call using the dialRegistrationFree() API.
  • If the application uses a third-party SIP SDK instead of the Cloudonix Mobile SDK, a RegFree call can be started by adding the following headers to the INVITE message:
  • X-Cloudonix-Session - set to the session token from the incoming call notification.
  • X-Cloudonix-Domain - set to the Cloudonix domain for the subscriber.
  1. Cloudonix Subscriber Gateway intercepts the dial and validates the session token. If the token is invalid the call is rejected.
  2. Cloudonix Voice Application Server connects the subscriber's call to the incoming call.
  3. Cloudonix API Call Management Service’s Session Control - Ringing Notification returns a 200 (“OK”) HTTP response, letting the subscriber’s application’s know the session has been connected.

Call Rejection​

Incoming Call Cancellation - Callee Side​

In the Call Reception process if the receiving user wants to decline (reject) the call or the ringing timed out by the subscriber application, the subscriber application should notify the Cloudonix Platform that the call should be rejected, in one of two ways:

Customer's Server Terminates Call​

Diagram​

In Detail​

  1. Subscriber application notifies the customer's server application about the cancellation, including cancel reason - one of rejected or timeout.
  2. Customer's server application calls the Session Control - Destroy Session to notify the Cloudonix Platform about the rejection using the session token received in the incoming call notification.
  3. Cloudonix Voice Application Server disconnects the call, returning the appropriate status, as per the cancel reason, to the caller.

Subscriber Application Rejects Call​

Diagram​

In Detail​

  1. Subscriber application sends an HTTP DELETE request to the Session Control - Ringing Notification using the Cloudonix API server address, the receiving subscriber's MSISDN, and session token provided in the incoming call notification.
  2. Cloudonix Voice Application Server disconnects the call, returning the appropriate status, as per the cancel reason, to the caller.

Incoming Call Cancellation - Caller Side​

During a call to a RegFree™ subscriber, if the caller decides to cancel the call, they disconnect the call from their side. The Cloudonix Voice Application Server cancels the session In the progress and causes the Cloudonix API Call Management Service’s Session Control - Ringing Notification to return a 205 (“Reset Content”) HTTP response, to let the Callee know that the session was canceled.

Domain Configuration​

The behavior of the RegFree flow in Cloudonix is controlled by domain-level configuration stored in the domain profile. The domain profile can be edited using the Cloudonix Dashboard or through the Cloudonix API.Core REST API.

To enable RegFree support in a domain, set the field “registration-free-control-endpoint” to the URL of the customer's server application endpoint that should receive incoming call notifications from Cloudonix.

Additionally the following domain profile fields control RegFree behavior:

  • call-timeout - maximum time in seconds for the Cloudonix stack to wait for an incoming call to be picked up, before declaring the call “unanswered”. Default: 60

RegFree REST API​

The Cloudonix RegFree Dialing relies on both the Cloudonix platform providing the session management API to the subscriber application backend, as well as the customer's server application providing an API to allow Cloudonix to notify it of incoming calls.

The following section specifies the API the customer has to implement on their server application - the RegFree Control Endpoint API.

The Cloudonix Call Management Service API can be found in the Call and Session Control.

RegFree Control Endpoint API​

This API must be implemented by the subscriber application backend service, and the endpoint URL must be configured in the Cloudonix system by setting the domain profile attribute registration-free-control-endpoint to the URL of the subscriber application backend, using the Cloudonix Dashboard or using API.Core REST API - for example like so:

PATCH /domains/cloudonix.io HTTP/1.1
Host: api.cloudonix.io
Authorization: bearer XI1234567890
Content-Type: application/json

{
  "profile": {
    "registration-free-control-endpoint": "https://example.com/incoming"
  }
}

Incoming Call Notification​

This API is invoked by Cloudonix to notify the subscriber application backend of an incoming call to a specific subscriber.

POST <registration-free-control-endpoint>

Request​

The following data fields must be provided in the request body, as properties in a JSON object:

  • dnid - the MSISDN of the subscriber to which the incoming call it being terminated.
  • caller-id - the number that was reported to Cloudonix as the originating caller.
  • session - the RegFree™ session token that the subscriber should connect to.
  • subscriber - the Cloudonix subscriber record for the receiving subscriber account.
  • domain-id - the numeric domain identifier of the Cloudonix domain of the subscriber receiving the call.
  • domain - the domain name of the Cloudonix domain of the subscriber receiving the call.
  • endpoint - the URL to the API.Core API.
  • sip-headers - a convenience property that contains the content of the sip-headers Session Profile Properties, if it is set.

Response​

If the request is successful, the server must respond with any HTTP 200 class response (such as 200 “OK”, 201 “Created” or 204 “No Content”). The body of the response, if any, will be ignored.

If the request was not handled successfully because the subscriber MSISDN (in the dnid field) does not match an existing subscriber, the server must respond with an HTTP 404 (“Not Found”) error, to signal Cloudonix to reject the call. The body of the response, if any, will be ignored.

If the request was not handled due a temporary problem and Cloudonix should retry the transaction, the server must respond with an HTTP 500 class error response (such as 500 “Internal Server Error” or 503 “Service Unavailable”). The body of the response, if any, will be ignored.

Any other response will cause Cloudonix to reject the call with a permanent error status.

Example​

POST /incoming HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "dnid": "972547340014",
  "caller-id": "+15155558484",
  "session": "4b3239e2-ad9d-11e7-b2d0-33c35612ef0a",
  "subscriber": {
    …
  },
  "domain-id": 17,
  "domain": "example.com",
  "endpoint": "https://api.cloudonix.io",
}

HTTP/1.1 204 No Content