Real-time billing using OpenSIPS 2.3 and CGRateS

SIP without billing is like a dinner without a good wine. While OpenSIPS does a great job for SIP, it often needs a billing partner to work with. CGRateS is an open-source rating engine used for carrier-grade, multi-tenant, real-time billing. It is able to do both postpaid and prepaid rating for multiple concurrent sessions with different balance units (eg: Monetary, SMS, Internet Traffic). CGRateS can also export accurate CDRs in various formats.

So, the upcoming OpenSIPS 2.3 comes with a built-in integration with CGRateS. This is done via a new module that provides simple and efficient communication with the CGRateS engine. You can use this new feature to do call authorization and accounting according to the user’s billing profile and also generate CDRs.

Authorization

When a new call comes in, from the OpenSIPS script you can check if the caller is allowed to reach the dialed number. This is done via a simple scripting function that internally queries the CGRateS engine for the authorization. According to the account’s billing profile and the remaining balance, CGRateS can decide whether the user is allowed to call or not. If the answer is successful, CGRateS sends back a recommended call duration. OpenSIPS sets that duration as the dialog’s lifetime. This means that the call will be terminated after that period, ensuring that the account does not run out of credit while the call is ongoing. If CGRateS does not authorize the call, it will return an error. In this case, you can decline the call, or send it to a media announcement server.

And all this logic and communication is done by a simple script function call.

Accounting and Charging

After a call is authorized, one can engage the CGRateS billing in OpenSIPS. While OpenSIPS provides call events and metadata, the CGRateS engine is the one that will actually charge the account and eventually generate the CDRs.

Note that the charging does not start immediately, but when the call is answered – when a 200 OK comes in, OpenSIPS issues a new command to CGRateS starting a new billing session for that account. When the call terminates, either by one of the parties closing it, or by a different logic (dialog timeout, manually triggered dialog termination, etc.), OpenSIPS sends a new command to terminate the session. At this point, CGRateS charges the account according to its profile, the destination called and the duration of the call.

Due to the fact that the accounting only starts when the call is answered, it is important to first authorize the call – make sure the caller is indeed allowed to call to that destination. Otherwise, if the user is not allowed to make the call, the call will be immediately closed by OpenSIPS, resulting in a zero-duration call with zero charge.

A typical example of using the CGRateS module in OpenSIPS is the following snippet used for initial INVITEs:

...
if (!cgrates_auth("$fU", "$rU")) {
    send_reply("403", "Forbidden");
    exit;
}
xlog("Call is allowed to run $cgrret seconds\n");
# do accounting for this call
cgrate_acc("cdr", "$fU", "$rU");
...

CDRs (Call Detail Records)

When the call is completed, OpenSIPS can instruct CGRateS to generate CDRs for it. Along with standard CDR fields such as account, call identifier, duration, cost, etc., OpenSIPS can also push custom values from the script. All CDRs are gathered by the CGRateS engine and can be forwarded to a HTTP server, or simply exported as (CSV) files.

Note that OpenSIPS can still generate CDRs independently of the CGRateS module using the acc module. However, these CDRs will not have the cost of the call, because that is determined by the billing engine.

Remarks

Although the new module provides a simple way of integrating with the CGRateS engine, it still offers the means to create various and powerful scenarios, such as postpaid vs prepaid, with or without call authorization, custom CDRs generation, etc.

This work is the result of the fruitful collaboration between the OpenSIPS and the CGRateS teams, in terms of interest, ideas and effort.

Together with the ongoing work on Homer and FreeSWITCH integration, this brings us one step closer to a achieve a unified VoIP/SIP solution. Of course, in the benefit of our communities.