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:

       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:


       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:
  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>.


  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

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

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
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.
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
Ringback Time
How long to indicate ringing in seconds.
0 seconds
Ringback Type
How to indicate ringing. Possible values are 'indicate' and 'earlymedia'
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
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.
Force CLI Authentication
Reject calls from unknown CLIs. Can be used together with Force Default Account option.
Force Default Account
Always make the Default Account to be owner of the first callback call leg.
The Reason For Diversion *
The reason parameter for the Diversion SIP header

* starting from Sippy 2020

CLD options

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
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
The callback call is originated with this identity.
This field is used to reschedule the callback call
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.
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.
Statistics field indicating the connect time. It is NULL for failed calls.
Statistics field containing date and time of request creation.
First call leg of this callback call will be terminated in specified amount of seconds. This field is optional and defaults to NULL.
If the default callback user was chosen during callback request creation (see the Callback->DefaultUsername parameter)
Statistics field indicating the end of the callback call
If True then this record is statistics entry. Otherwise the record is schedule entry.
The primary key
HA1 hashed password of the user. HA1 is calculated as MD5 of the string "<username>:<realm>:<password>" (without quotes).
This field is used to reschedule the callback call
Original CLI
Use this CLI when creating callback call leg
Original CLD
Statistics field indicating the beginning of the callback call attempt
Callback result string (see below).
Callback status string (see below).
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.
Parameter for the 2WayCallback application.
Parameter for the 2WayCallback application.
Parameter for the 2WayCallback application.
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

Is application specific

Request received
Request received but not tried yet
First leg initiated
First leg initiated but not connected yet
First leg connected
First leg connected, and an IVR application started on the second call leg.
Second leg initiated
Second leg initiated but not connected yet
2 Way Callback
Second leg connected
Second leg connected and conversation takes place
2 Way Callback
Callback attempt succeeded

Possible intermediate and error conditions

Is application specific

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

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


  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.