Principle of operation


The ANI Callback IVR application can be configured in two different ways:

  1. Using a DID Pool and the IVR application menus (standard in the latest versions) 
  2. Using a connection with the IP of environment and port 5062 which belongs to the internal Asterisk service. 

The first scenario is a standard one that we use in systems that are higher than 3.x version.

       1. Open the IVR application menu and click Add New IVR application with Type = "Calling Card" 

           using the following instruction: http://support.sippysoft.com/solution/articles/183496-step-1-add-calling-card-ivr-application

       2. Open the IVR application menu again and click Add New IVR application with Type = "ANI callback" and with IVR Application (item #3 on image) that you have created in the item#1And then click "save" button to create it.

        See an example:

       3. After you save, add the needed options in the "Advanced Parameters" (scroll down the page to find the table with all available options) section of your application.

       4. Open the DID Pool section menu and add the DID number that later you will assign to the IVR application with Type = "ANI callback".

       5. Create a basic configuration of Sippy Softswitch using our video tutorial:

           https://sites.google.com/site/sippylearning/video-tutorials/home

       6. Create a special Account that you will use as a "Default Account" in the IVR application (for outgoing calls in scope of a callback service) where USERNAME should be used as a parameter.

       See example:

       7.  Make a test call to the DID number that you have tied to your ANI callback application. 
Please note, when you call to the Callback application, the system initiates a callback to your CLI number and if the CLI answers the call, the system activates a Calling card application that requests the caller to enter the card number for proper authorization. In Sippy, Accounts play the role of Card Numbers this means you just need to enter the USERNAME of the Account for authorization and then Calling Card will ask you to enter the destination number.


Below is described a second scenario of the ANI callback configuration that was used in older versions of Sippy Softswitch (in 3.x versions and lower).
  1. The ANI Callback application receives the call with the name of sub-application to invoke in its parameters (currently only CallingCard and 2Way Callback IVR applications are supported).
  2. The ANI Callback application checks if there is account matching incoming CLI for that call. The matchning performed against accounts table and then against calling_card_cli_map table to identify particular account.
  3. If both matches in previous step have failed then the ANI Callback application tries to take the default callback username from configuration. So all foreign CLIs are called back using the default callback username as authname.
  4. The ANI Callback application optionally indicates ringback via early media or sends ringing indication and then rejects incoming call without answering.
  5. If the match has been successful the ANI Callback application initiates new call to that CLI using credentials of the user identified on the previous step.
  6. If the call fails, the ANI Callback application makes several retries.
  7. When the call has been aswered, the ANI Callback starts specified sub-application and passes control to it.


Call routing setup

  1. Add vendor connection. Set the Asterisk's host/port in the Destination field of Vendor Connection (ex: 192.168.0.100:5062).
  2. Set the CLD Translation Rule for the connection to the value ani_<options>_<string>. For possible options please refer to the section CLD options below.
  3. Add route to this connection to specify the ANI Callback Extension number.

When user calls the specified extension the IVR server arranges the callback call and dials the user back in several seconds. The IVR applications consider this callback call as ordinary call with the CLI identical to original call and with CLD set to <string>.


Example:

  1. The Vendor connection has been created with the CLD Translation rule of ani_callingcard_en_th.
  2. The user 801 called the callback extension and hanged up.
  3. The IVR server calls the user and user picks up the phone.
  4. The IVR session starts with the CLI 801 and CLD callingcard_en_th.
  5. As expected the Calling Card application recognizes the call and handles it.


Available options for the "Advanced parameters" section of IVR application


Option
Meaning
Default
Backoff Interval
Failed attempts to make callback call will be retried after this amount of time
10 seconds
Default Account Username
The default account to use for CLIs that are not local accounts

Enable_Anonymous_Accounting
Should the real account also be charged for the first call leg of the callback call when using the Default Account. This option is the same as CLD option noanonacct
True
Delay Before Callback
First callback attempt will be performed not earlier than this time has passed
5 seconds
Hangup SIP Response Code
Which SIP response code to use when hanging up. Possible hangup codes you can see here.
603
Minimum Balance
The minimum allowed balance when the account is accessible. When balance is lower then this threshold then the default user will be tried. The value can be suffixed with a currency (e.g. '2 USD') in which case it will be converted to the user's currency prior to comparison.
Not set
Max # Of Callback Attempts
The maximum number of attempts to call back before the call canceled
3
Ringback Time
How long to indicate ringing in seconds.
0 seconds
Ringback Type
How to indicate ringing. Possible values are 'indicate' and 'earlymedia'
'indicate'
SIP Proxy For Callback Calls
SIP proxy to use when doing the outbound calls
local IP address
Scan Interval
The time between attempts to find new callback calls
5 seconds
Timeout
Time to wait for answer
300 seconds
Fixed CLI
This value is used as CLI on the first call leg of the callback call.

Disable CLI Authentication
Completely disable CLI authentication. Useful together with Default Account Username option.
False
Force CLI Authentication
Reject calls from unknown CLIs. Can be used together with Force Default Account option.
False
Force Default Account
Always make the Default Account to be owner of the first callback call leg.
False
The Reason For Diversion *
The reason parameter for the Diversion SIP header
unconditional

* starting from Sippy 2020

CLD options


Option
Description
noanonacct
Should the real account also be charged for the first call leg of the callback call when using the Default Account. This option is equivalent to the Enable Anonymous Accounting option.


Database usage


The application uses callback_requests table to store new callback requests and completed call statistics.

Description of fields of the table callback_requests


Field name
Description
anon_acct_enabled
This field can help to enable or disable an accounting for calls which use the Default Account. When the accounting enabled, then a SIP header X-2Way-Need-Bind: yes is included in the INVITE SIP request while creating second call leg so to inform b2bua that the account making this outbound call should also be charged for the first callback call leg. Default is True
authname
The callback call is originated with this identity.
call_count
This field is used to reschedule the callback call
call_id
This field can be preset to some value in which case the callback call will use this Call-ID. If the field contains NULL then the random value is generated and placed in this field during the call.
canceled
This field is intended to be set from elsewhere (XMLRPC for example). The corresponding call is forcibly canceled when this field is set to True.
connect_time
Statistics field indicating the connect time. It is NULL for failed calls.
creation_time
Statistics field containing date and time of request creation.
credit_time
First call leg of this callback call will be terminated in specified amount of seconds. This field is optional and defaults to NULL.
default_user_used
If the default callback user was chosen during callback request creation (see the Callback->DefaultUsername parameter)
disconnect_time
Statistics field indicating the end of the callback call
finished
If True then this record is statistics entry. Otherwise the record is schedule entry.
i_callback_request
The primary key
md5secret
HA1 hashed password of the user. HA1 is calculated as MD5 of the string "<username>:<realm>:<password>" (without quotes).
next_call
This field is used to reschedule the callback call
original_cli
Original CLI
original_set_cli
Use this CLI when creating callback call leg
original_cld
Original CLD
setup_time
Statistics field indicating the beginning of the callback call attempt
result
Callback result string (see below).
status
Callback status string (see below).
twoway_call_id
This field can be preset to some value in which case the call to destination will use this Call-ID. If the field contains NULL then the default value is constructed based on call_id and placed in this field during the call.
twoway_cli
Parameter for the 2WayCallback application.
twoway_authname
Parameter for the 2WayCallback application.
twoway_md5secret
Parameter for the 2WayCallback application.
username
The callback call is originated on behalf of this user


Status and result strings


Status and result are set by the callback subsystem and can also be extended by some applications. Currently 2 Way Callback Application is able to set own specific statuses and results.


Main flow


Order
Status
Result
Description
Is application specific





1
Request received
NULL
Request received but not tried yet
No
2
First leg initiated
NULL
First leg initiated but not connected yet
No
3
First leg connected
NULL
First leg connected, and an IVR application started on the second call leg.
No
4
Second leg initiated
NULL
Second leg initiated but not connected yet
2 Way Callback
5
Second leg connected
NULL
Second leg connected and conversation takes place
2 Way Callback
6
Finished
Successful
Callback attempt succeeded
No


Possible intermediate and error conditions


Status
Result
Description
Is application specific




Waiting for retry
NULL
Callback attempt was unsuccessful but some more attempts are allowed
No
Finished
Out of retries
All possible attempts to call back have failed
No
Finished
Expired
The callback request was too old to even try it. This can happen if ivrd has been down for too long
No
Finished
First leg aborted
First call leg has hanged up before second call leg connects
2 Way Callback
Finished
Second leg failed
Second call leg has been rejected
2 Way Callback
Finished
Canceled
Call was canceled by administrator.
No


Supported hangup SIP response codes


403 Forbidden
404 Not found
408 Request Timeout
410 Gone
480 Temporarily unavailable
484 Address incomplete
486 Busy here
488 Not Acceptable Here
500 Server internal failure
501 Not Implemented
503 Service Unavailable
502 Bad Gateway
603 Declined


Notes

  1. Max. Sessions parameter of the callback account should be equal to or greater than 2. Otherwise the second call leg won't go through.