Setting up SMS Callback Services



General Configuration of Callback Services

Sign up and Configure the SMS Delivery Service

Add a New SMS Callback Trigger Instance

Configure the Instance Parameters

Create a Tariff for End Users

Enter Rates

Create a Product

Create a Customer

Create a Template Account

Generate Vouchers



The concept behind an SMS callback is that an end user sends an SMS from his / her mobile phone. The information contained in the SMS is processed and then used to initiate a callback.


However, the question is: how will an SMS reach your PortaSIP® Media Server? The answer is by delivering SMS messages via a hosted SMS provider. This provider takes care of interconnecting with wireless carriers around the world, and provides you with a consolidated SMS flow (using a well-documented API) and a centralized management and billing interface. One good example of such a company is Connection Software ( Integration with their system is fully supported by PortaSwitch®.


This chapter demonstrates how to sign up for the Csoft SMS delivery service and perform further configurations of PortaSwitch®.


Consider the following example:

A user from Ukraine wants to call Australia. He sends an SMS to register his phone number and to top-up his balance. Then he sends another SMS that contains the Australian destination number. The user receives a callback on his phone and is connected with Australia.


Print the following page and use it to mark the operations you have completed while performing the system setup according to the instructions in this chapter. Please make sure that you perform all of the operations in the order designated (all of the boxes should be checked), otherwise the service will not work.




Sign up and configure the SMS delivery service within the Csoft system

[     ]

General configuration


Enable the Callback Module

[     ]

Voice Application configuration


Add a new SMS callback trigger instance

[     ]

Configure the parameters of the SMS callback trigger instance

[     ]

Rating configuration (Customer)


Create a tariff A, which will be applied to the end users for using callback

[     ]

Insert rates in tariff A for the destinations the callback will be used for (legA,) and to which your customers will make outgoing calls (legB)

[     ]

Create your product for callback services

[     ]

In the rating list (of the callback product) include a rating entry that will contain your PortaSIP® node and tariff A containing the callback calling rates

[     ]

Account provisioning


Create a retail customer as the account owner for callback services

[     ]

Generate a batch of vouchers (PINs) for this customer

[     ]

Create a template account

[     ]



Send an SMS to the access number and initiate a test callback

[     ]

General Configuration of Callback Services

Follow the steps described in the Setting up Callback Services. General Configuration handbook that contain the initial instructions for configuring callback services.

Sign up and Configure the SMS Delivery Service

1.     Go to the Csoft web page ( and create an account there.

2.     Log in using your account credentials.


Configure the two-way sms service


3.     From the Configure Services list click on the Two-way – Setup & configure.


Select the option


4.     Click the Setup & Configure option; select Purchase and Two-Way Service Option 3 from the list boxes.

5.     Click Continue.


Choose the delivery method


6.     Click I would like messages to be delivered back to me using an HTTP POST to my website option.

7.     Click Continue.


Fill in the SMS to HTTP POST configuration parameters


8.     Fill in the SMS to HTTP POST configuration parameters:

·       URL – Specify the URL of your PortaSIP® Media Server in this format: http://<host>:8903 (where host is a callback domain name of your PortaSIP® Media Server, and 8903 is the port on which SMS callback operates.)

·       Username – Specify the username that will be used to access your HTTP server (e.g. ANOther.62134)

·       PIN – Type in the PIN that will be used to access your HTTP server. The PIN is provided to you during your account registration. It can be found on the Account details page.

9.     Click Continue.

10.   Click Finish to finalize the Two-way service configuration.


Receive an access number for messaging


11.   Upon completion of the configuration, you will be provided with an access number that will be used to deliver SMS to and from your PortaSIP® Media Server (+447717989603 in this example).


_Hint_Glasses TIP: To enable a secure connection between the SMS provider and your PortaSIP® Media Server, specify the URL in this format: https://<host>:8904.

Add a New SMS Callback Trigger Instance

1.     On the navigation menu, select Infrastructure, then select Voice calls processing and go to Voice applications.




2.     On the Create voice application panel, fill in the following fields:

·       Name – specify the name (e.g. Free SMS).

·       Application type – choose SMS callback trigger.


 Create a Voice application


3.     Click Save.

Configure the Instance Parameters

1.     On the Voice application panel, go to the Entry point panel and specify Callback access number. This is the number where the users will send SMS messages to. You received this number after having configured the SMS service within the hosted SMS provider system.


Specify an Entry point


2.     Go to the Authentication, Authorization, Accounting section and configure the following parameters:

·       On the Accounting panel, specify the access code in the Access code field that will allow the PortaBilling® to use a special tariff for callback charging. For SMS callback, the default access code value is SMSCALLBACK.


Enable the Special charge if LegB fails option to use a special tariff to charge for legA if a call to a destination number (legB) cannot be established (e.g. if the destination number is busy or not answering).


Specify an access code


·       On the Translation rules panel, put a cursor into Account ID translation rule field and specify the translation rule that will be applied to accounts.


Specify the Translation ruls


3.     On the Prompts & notifications panel, go to the Prompts customization section and specify the folder name with your custom IVR prompts. These prompts will be used instead of the default ones. Please refer to the How to… section for a detailed description of how to upload and use custom IVR prompts.


Configure the Brand prompts


4.     On the Application specific panel, specify the Template account ID that will be used for creating new accounts upon registration. Then go to SMS provider credentials panel and specify the following parameters:

·       Inbound provider – Select Csoft here.

·       Outbound Provider – Select Csoft here.

·       Send SMS login – Specify your account’s username created within the hosted SMS provider system.

·       Send SMS password – Specify the PIN you provided when configuring the SMS service within the hosted SMS provider system.

·       Send SMS URL – Specify the web address of the SMS provider (for Csoft it is


Application specific configuration


5.     Click Save.

Create a Tariff for End Users

Now it is necessary to create a tariff according to which your customers will be charged for using the callback services.

A callback call consists of two parts (call legs): a call to the calling party (legA) and a call to the destination number (legB), therefore this tariff will be used to create charges for both call legs. The total charge for the whole callback call is the sum of charges for call legA and call legB.


1.     On the navigation menu, select Service catalog and click Tariffs.

2.     On the Create tariff panel, fill in the tariff details:

·       Name – Type a short name for the tariff object; this is the name you will see in the select menus, (for example, Callback).

·       Currency – This indicates the currency in which you charge your customers.

NOTE: The currency for the tariff is chosen only once, and cannot be changed later.

·       Service – Select Voice Calls.

·       Applied to – Select Customer as this tariff will be used to charge your customers.

·       Managed by – Select Administrator only here, since we are setting up a service without the involvement of resellers.


Create a tariff


3.     Click Save.

NOTE: You can charge separately for call legs. Please refer to the How to section for a detailed description of the necessary steps for setting that up.

Enter Rates

Since a callback call consists of two call legs, rates for both call leg destinations must be entered into the tariff.


Add rates to the tariff


1.     On the Add rate panel, fill in the rate details:

·       Destination – A destination prefix may be entered directly (e.g. 380 for Ukraine) or you can access the destinations directory by clicking the Destination link (in the column header). Here you will find all prefixes listed by country name.

NOTE: You should create an entry for certain phone prefixes in the Destination register before creating a rate for them in the tariff.

·       First interval, seconds – Type a first billing unit in seconds.

·       Next interval, seconds – Type the next billing unit in seconds.

·       First price – Type a per minute price for the first interval.

·       Next price – Type a per minute price for the next interval

·       Off-peak first interval – Type a first billing unit in seconds for off‑peak time.

·       Off-peak next interval – Next billing unit in seconds for off‑peak time.

·       Off-peak first price – Type a per minute price for first interval for off‑peak time.

·       Off-peak next price – Type a per minute price for next interval for off-peak time.

NOTE: Off-peak fields appear only if this tariff has already been assigned an off-peak period on the General info panel.

·       Rate formula – Type a custom rating formula.

·       Effective from – If you want this rate to take effect sometime in the future, you can either type in a date manually, or use the calendar (click on the DD-MM-YYYY link).

NOTE: When using the calendar, you can specify that the date you are entering is in a different time zone than your present one. PortaBilling® will then automatically adjust the time.

2.     Click Save.

3.     Repeat these steps to enter more rates.

Create a Product

Accounts for accessing callback services will have a specific product assigned to them. Products are powerful tools that define different ways for billing accounts. Product definition is always done using these steps: product type definition, service definition and configuration, and creation of a rating list.


Create a Product


1.     On the navigation menu, select Service catalog and click Products.

2.     On the Create product panel, fill in the product details:

·       Name – Type an internal product name that will be shown on the administrator interface.

·       Name visible to end users – Type a name of the product that will be shown to end users on their self-care interfaces.

·       Product type – Select Main product here.

·       Currency – Choose a currency the product will be priced in.

·       Managed by – Select Administrator only here, since we are setting up a service without the involvement of resellers.

·       Account default ACL – Choose an Access Control List (ACL) for accounts with this product assigned. ACLs control which objects end users can access to and which actions they can perform.

·       Account role – Select Universal from the list.

3.     Click Save.

Included Services tab

Define which service types are included in the product. A service type is a description of the physical service provided to end users.

To add a service type:

1.     On your product’s panel, click Services.

2.     On the Services panel, click Add a service.

3.     In the Select services to add dialog box, select Voice calls and click Add.


Fill in the product information

Usage Charges tab

The rating list has two functions: it defines permitted access points (nodes and access numbers) and specifies which tariff should be used for billing in each of these points.


1.     On your product’s panel, click Charges, then click Usage charges.

2.     On the Usage charges panel, click Add.

3.     Fill in the required information:

·       Service – Select Voice Calls.

·       Node – Select the PortaSIP® node.

·       Access code – Type in the SMSCALLBACK access code here. You can also leave this field empty; the system will automatically select the tariff when charging for SMS Callback services.

·       Tariff – Select the tariff that will be used to calculate the charges for callback calls.

·       Overdraft protection – To configure overdraft protection for this product, consult the Configure Overdraft Protection Section within the Product section in the Overdraft Protection Configuration handbook.


4.     Click Save.



1.     Click Add to enter another rating entry. This rating entry will define what tariff should be selected if one of the call legs fails to be established (e.g. the destination number is busy or not answering).

2.     Fill in the required information:

·       Service – Select Voice calls.

·       Node – Select the PortaSIP® node.

·       Access code – Type in the CALLBACK_FAIL access code here.

·       Tariff – Select the callback tariff for unsuccessful calls.

NOTE: You can use a special tariff for this rating entry (e.g. if you do not charge your customers for unsuccessful calls to destination numbers, create a separate tariff and enter a rate of zero for a “|” wildcard destination in it). Find the description of the tariff creation and rates enter in the sections above.


3.     Click Save.

Create a Customer

A customer owns their accounts. As a rule, Callback is provided as a prepaid service, so invoices are not issued. However, you will still need at least one customer object in order to keep all the accounts organized in one location.


1.      On the navigation menu, select Sales, then select Customers.

2.     On the Create customer panel, fill in the customer details:

·       Name – Type a short name for the customer object; this will be used on the web interface.

·       Business model – A business model defines what type of service is to be provided to the customer. Select Universal for this customer.

·       Customer class – Customer class allows you to define a policy for automated payment collection. By choosing a specific class here the customer will automatically inherit all of the class properties (grace period, invoice template, etc.).

·       Billing period – Choose a billing period for the customer. A billing period defines the frequency of invoicing for this customer.

·       Billing period time zone – Choose a time zone in which customer’s billing period will be closed and invoices will be generated.

·       The last day of the billing period – This is a read-only field available only during customer creation. It shows the last date of the customer’s first billing period. Note that this date is shown in customer’s time zone.

·       Balance control – Select Postpaid.

·       Currency – Choose the currency in which this customer will be billed.

·       Credit limit Specify the credit limit value for this customer.



3.     Click Save.

Create a Template Account

1.     On your customer panel, click Accounts.

2.     On the Create an account panel, fill in the account details:

·       ID – The name that you will have to specify in the Template account field of the SMS Callback Trigger instance (e.g. default@ivrutil).

·       Account role – Select Universal.

·       Product – Select the product you just created (Callback Services).

·       Activation date – Leave the default value as is. The account will immediately be activated.

·       Service password – Specify the service password for this account. It is very important to assign a secure (difficult to guess) password to prevent the account from being wrongfully entered and used to inject fraudulent calls to your network.

·       Type – Select Credit.

·       Balance control – Select Subordinate.


Create an Account


3.     Click Save.

Generate Vouchers

Before generating vouchers create a Product with Voucher Account role. To create a Product, consult the Create a Product section in this handbook.

NOTE: Before generating accounts for a production system, read the Provisioning Prepaid Accountssection.

1.     On your customer’s panel, click Accounts.

2.     On the Create an account panel, click Account generator.

3.     In the Account generation dialog, fill in information about accounts.

Initial configuration

·       Account role – The defined usage for the account. Select Voucher from the list.

·       Product – Choose the main product, which you would like your account to have.

·       Quantity – Number of accounts (vouchers) to be generated.

·       Batch – Accounts are grouped into batches. If Add a new batch is selected, all accounts will be placed into a new batch. Otherwise, an existing batch should be selected from the drop-down list.

·       New batch name – Type a name for the new batch.


Initial configuration


Optional configuration

·       Opening balance – The initial balance on the vaucher. Type in 10 here.

·       Requires manual activation – It is normal practice to generate all vauchers as inactive so they cannot be misused before being sold to the dealer or end customer. Move the slider to the right to generate as inactive.

·       ID prefix – If you would like all of the generated accounts to start with the same digit string (e.g. 12), enter it here. Thus, if you enter 12 and an ID length of 10, account IDs (PINs) will look like this: 12NNNNNN, where N = random digits.

·       ID length – All account IDs (PINs) will be numerical and of the specified length. In order to avoid problems with the prepaid card print-shop, PortaBilling® will not generate account numbers with a leading zero. Also, PortaBilling® will only allow generation of a batch with feasible parameters, e.g. it is impossible to generate a batch of 1,000 accounts with ID length 4 and ID starting at 55.

·       Service password – To improve security, you can use the complete account information, i.e. account ID and password, for authentication in an email callback. Click Auto Generated so that service passwords are automatically generated.

·       Distributor – You can assign a specific distributor to this group of accounts.

·       Life cycle:

o   Activation date – The date from which the account is usable.

o   Expiration date – The date that the account expires.

o   Availability period after first usage, days – Defines the number of days the account remains active after its first use or recharge.

o   Availability period after last usage, days – Defines the number of days the account remains active after its last use or recharge.

·       Web self-care:

o   Credentials – If you choose Auto-generated, your customer will use his account ID (PIN) to login to the self-care pages; a random password for web access will be assigned for each account. If you choose Empty, the account owner will not be able to use the self-care pages at all until a login has been assigned for his account; no password will be assigned, so account owners will be able to login to the web interface simply by providing their account ID (PIN).

o   Time zone – When an account owner accesses the web self-care pages to see a list of his calls, the time will be shown in the time zone most appropriate for him.

o   Web interface language – The language to be used on the account self-care web interface.


Optional configuration


4.     Click Generate.

NOTE: Account generation tasks are executed every few minutes, and it may take a while to generate large numbers of accounts.

_Hint_ExclamationMark Notification about the generated cards will be sent by email to the user who created them. A CSV file with information about the new accounts will be attached.


A CSV file with information about the new accounts


_Hint_Glasses In case the original email message was lost or accidentally deleted, the file containing generated accounts is stored on the slave PortaBilling® server in the user /porta_var/<Server_IP>/ directory, sub-directory cards.


Register a new account

1.     Send an SMS to the access number with the following command:

R (registration only) or R NNNNNN (registration and account top-up).

NOTE: Mind the space after R.

Here R stands for registration and NNNNN is the recharge voucher number.


Send a test message


2.     As soon as the account is created (on the basis of the default@ivrutil template account), a confirmation SMS will be sent to you stating that the account with the exact account ID as your mobile phone has been created.


Receive a confirmation SMS

Initiate a callback call

1.     Send an SMS to the access number with the following command: DNNNNNNN or DN NNNNNNN.

Here NNNNNNN stands for the destination number.

Initiate a callback call


2.     Wait for a call to your phone number.


Please refer to Appendix B “SMS Callback Commands” in the PortaSIP Media Applications guide for a detailed description of other commands available.