Kazoo Rating Engine

Kazoo Rating Engine

Build Your Own Rating Engine

Here are the steps to easily add your own rating engine to Kazoo (and bypass the HotOrNot WhApp).

How calls are rated in Kazoo

When a new call is received in the ecallmgr application, a rating request is published onto the AMQP bus. Any application bound for those rate request events will receive the JSON payload and can optionally respond with a rate response. The first valid response received will be the rate applied to the call.

Rate Request JSON

Kazoo generates a rate request payload published onto the callmgr exchange with a routing key of rate.req. The JSON payload will look something along the lines of:

Rate Request JSON:

{To-DID:+14158867900
,Call-ID:abc123def456ghi789
,Event-Category:rate
,Event-Name:req
,Msg-ID:msg_id_9876
,Server-ID:amqp_queue_name
,App-Name:sending_app
,App-Version:sending_app_ver
,Node:ecallmgr@host.com
,Account-ID:qwerty1234567890
,From-DID:+14158867915
,Options:[] 
,Direction:inbound

}

Description of the Rate Request JSON payload:

Value : Required
To-DID: The dialed number
The dialed number off the INVITE
Yes
Call-ID: The unique identifier for this channel
String: Yes
Event-Category: The class of event
Rate: Yes
Event-Name: The name of the event
Req: Yes
Msg-ID: The ID of this rate request message
String: Yes
Server-ID: The name of the AMQP queue of the sender, empty if no response is needed
String: Yes
App-Name: The name of the application that published the request
String: Yes
App-Version: The version of the application that published the request
String: Yes
Node: The **Erlang** VM node name of the sender
String: Yes
Options: Arbitrary list of strings set by sender, usually used by receiving to filter list of applicable rates
List of strings: No 

Direction

The direction of the call, relative to Kazoo; outbound: meaning from Kazoo to the endpoint and inbound: meaning from the endpoint to Kazoo inbound/ outbound:No

“ Account-ID: The Kazoo account ID associated with this cal (if any) String: No From-DID : The Caller ID number (if available) String: No


## Route Response JSON

Any application which receives rate requests and wishes to respond will need to publish the response to the targeted exchange using the Server-ID from the rate request payload as the routing key. Assuming the request above, a potential response would be constructed thusly:

**Rate Response JSON:**

    {Rate:0.05
    ,Call-ID:abc123def456ghi78
    ,Rate-Increment:60
    ,Rate-Minimum:60
    ,Discount-Percentage:0
    ,Surcharge:1.00
    ,Rate-Name:expensive_rate
    ,Base-Cost:1.05
    ,Msg-ID:msg_id_9876
    ,Update-Callee-ID:true
    ,Event-Category:rate
    ,Event-Name:resp
    ,App-Name:hotornot
    ,App-Version:1.0.0
    ,Server-ID:
    ,Node:whistle_apps@host.com

    }

Description of the Rate Response JSON payload:

Value: Required
Rate: The cost of the rate
Float: Yes
Call-ID: Identifier of the channel
String:Yes
Event-Category: Class of message
Rate:Yes
Event-Name: Name of the message type
Resp: Yes
App-Name: Name of the responding application
String: Yes
App-Version: Version of the responding application
String: Yes
Msg-ID: The ID from the request payload that identifies the request message
String: Yes
Node: The responder's node (useful mostly for debugging)
String: Yes
Server-ID: Empty, since no response to this message will be sent
Rate-Increment: How many seconds before Rate is applied
Integer (defaults to 60): No
Rate-Minimum: Minimum number of seconds to bill the call for, regardless of call duration
Integer, defaults to 60: No
Discount-Percentage: Apply a discount to the cost of the call
Integer: No
Surcharge: Flat amount to bill the call (in addition to per-minute charges)
Float: No
Rate-Name: Arbitrary name for the rate
String: No
Base-Cost: (Rate * (Rate-Minimum div 60)) + Rate-Surcharge
Float: No
Update-Caller-ID: If `true`, will prepend the Callee ID name with the rate of the call
Boolean, defaults to `false`: No

Rate Field

The rate fields (Rate, Rate-Increment, etc) will be set on the channel and available in the Custom-Channel-Vars of the resulting CDR. A simple formula is used to calculate the cost of the call:      R = Rate RI = Rate-Increment RM = Rate-Minimum Sur = Surcharge Secs = Billing Seconds When RM 60 = Sur + ((RM / 60) * R) When RM = 60 = Sur + ((RM / 60) * R) + ceiling((Secs - RM) / RI) * ((RI / 60) * R)))