Principle of operation
The ANI Callback IVR application can be configured in two different ways:
- Using a DID Pool and the IVR application menus (standard in the latest versions)
- 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#1. And 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).
- 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).
- 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.
- 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.
- The ANI Callback application optionally indicates ringback via early media or sends ringing indication and then rejects incoming call without answering.
- 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.
- If the call fails, the ANI Callback application makes several retries.
- When the call has been aswered, the ANI Callback starts specified sub-application and passes control to it.
Call routing setup
- Add vendor connection. Set the Asterisk's host/port in the Destination field of Vendor Connection (ex: 192.168.0.100:5062).
- 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.
- 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:
- The Vendor connection has been created with the CLD Translation rule of ani_callingcard_en_th.
- The user 801 called the callback extension and hanged up.
- The IVR server calls the user and user picks up the phone.
- The IVR session starts with the CLI 801 and CLD callingcard_en_th.
- 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
- Max. Sessions parameter of the callback account should be equal to or greater than 2. Otherwise the second call leg won't go through.