Setting up SMS Callback Services

Overview

Checklist

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

Testing

Overview

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 (http://www.csoft.co.uk/). 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.

Checklist

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.

 

Operation

Done

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

[     ]

Testing

 

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 (http://www.csoft.co.uk/) 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.      In the Routing section of Admin-Index, choose IVR Applications.

2.      Click Voice Applications Settings.

 

 IVR applications page

 

Add a new SMS callback trigger instance

 

Add the instance name

 

3.      Click Wor3AA3 Add a new instance under the SMS Callback Trigger menu and type the name of the instance into the pop up window.

4.      Click OK.

Configure the Instance Parameters

Configure the instance parameters

 

1.      Click on the SMS callback trigger instance you have just created.

2.      Fill in the following information:

·       Callback Access Number – Specify the access number where the users will send SMS messages to. This is the number you were given after having configured the SMS service within the hosted SMS provider system.

·       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 https://www.csoft.co.uk/sendsms).

·       Account ID Translation Rule – Specify the translation rule that will be applied to accounts.

·       Template Account – Specify the template account ID that will be used for creating new accounts upon registration.

·       Brand Prompts – 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.

·       Special Charge if LegB Fails – When this check box is selected, a special tariff will be used to charge for legA if a call to a destination number (legB) cannot be established (e.g. if the destination number is busy or doesn’t answer).

·       Access Code – Specify the access code that will allow PortaBilling® to use a special tariff for callback charging. For SMS callback, the default access code value is SMSCALLBACK.

3.      Click save_close Save & Close.

NOTE: There is a helpful tool-tip for each option. Just point your mouse to the desired option to bring it up.

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.

 

Create a tariff for end users

 

Add the tariff information

 

1.      In the Rating section of the Admin-Index page, choose Tariffs.

2.      On the Tariff Management page, choose https://demo.portaone.com:442/images/icons/add.gif Add.

3.      Fill in the Add Tariff form:

·       Name – A short name for the tariff object that will be used in the select menus.

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

NOTE: The currency for the tariff can only be chosen once; it cannot be changed later.

·       Applied To – Choose the Customer in the Applied To field.

·       Managed By – Choose Administrator only here.

·       Service – Choose Voice Calls.

4.      Click save 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.

 

Enter rates

 

Add rates information

 

Ckeck rates added

 

1.      While on the Tariff Management screen, click the https://demo.portaone.com:442/images/icons/editRate.gif Rates icon.

2.      On the Edit Rates screen, click https://demo.portaone.com:442/images/icons/add.gif Add.

3.      Fill in the required information:

·       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 the phone prefixes in the Destination register before creating a rate for them in the tariff.

·       Interval First – first billing unit in seconds.

·       Interval Next – next billing unit in seconds.

·       Price First – per minute price for first interval.

·       Price Next – per minute price for next interval.

4.      Click the save Save button in the toolbar, or the save_add Save icon on the left side of the row.

5.      Repeat these steps if you need 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

 

Add the product information

 

1.      In the Rating section of the Admin-Index page, choose Products.

2.      On the Product Management page, click the https://demo.portaone.com:442/images/icons/add.gif Add icon.

3.      Fill in the “New product” form:

·       Product Name – Type in the internal name of the product.

·       Product Name Visible to End User – Specify the name of the product that your customers will see on their self-care interface.

·       Account Role – Select Universal from the list.

·       Currency – Specify the product currency; only tariffs which have the same currency will be permitted in the rating list.

·       Product Type – Choose Main Product here.

Included Services tab

·       Service Type – Select the Voice Calls check box.

Usage Charges tab

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

 

Add usage charges

 

Add rating entries for SMS callback

 

·       Click Add to add a new rating entry.

·       Choose Voice Calls in the Service select menu.

·       In the Node select menu, 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.

·       In the Tariff menu, select the tariff that will be applied to your customers.

·       Click Update.

 

Add rating entries for callback fail

 

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

5.      Fill in the required information:

·       Node – Select the PortaSIP® node.

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

·       Service – Choose Voice Calls.

·       Tariff – Select the tariff you have just created for unsuccessful calls to destination numbers .

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.

·       Click Update.

Additional Info tab

·       Breakage – Specify the minimum amount of funds the account should have to be able to use services.

·       Description Visible to End User – Provide a description to be shown to end users on their self-care interface.

·       Description – Your comments about the intended use of this product.

·       Click Next.

Notepad tab

Leave your notes about this product. Insert a timestamp (current time of your time zone) by clicking Time Stamp.

 

6.      Click Done.

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.

 

Create a customer

 

In the Participants section of the Admin-Index, choose Customers.

 

1.      On the Customer Management page, click https://demo.portaone.com:442/images/icons/add.gif Add Customer.

2.      Fill in the New Customer form. Please note that there are several tabs with extra information available on the screen. The most important fields are:

Main form (top)

o   Customer ID – Short name for the customer object; will be used on the web interface.

o   Customer Class – Choose Default customer class, since invoicing and payment collection parameters defined by customer class are not really applicable to this customer, who is merely a placeholder for prepaid callback accounts.

o   Balance Control – Choose Prepaid from the list.

o   Currency – The currency in which the prepaid cards will be generated.

o   Permanent Credit Limit Assign a credit limit for the customer.

3.      Click save_close Save & Close.

Create a Template Account

1.      Go to the Customers screen (the screen which contains a list of customers). It should resemble the screenshot below:

 

Create a template account

 

Add an account

 

Add the account info 

 

2.      Next to the customer name, click on the Account https://demo.portaone.com/images/icons/no_accounts.gif Accounts icon (the one in the Accounts column), which will take you to the account management for that customer.

3.      Click on the https://demo.portaone.com:442/images/icons/add.gif Add icon.

4.      Fill in the Add Account form:

o   Account Role – Select the type of the account. Select Universal from the list

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

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

o   Blocked – You may create your account as blocked, although this is rarely done with SIP service accounts.

 

Account Info tab

o   Type – Account type; select debit for prepaid service.

o   Opening Balance – Specify a zero value so that an end user can consume services only after the account is topped-up.

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

Products tab

o   Main Product – choose the product you have created for the callback services.

Life Cycle tab

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

o   Specific Date – Identifies the date that the account expires.

o   ____days after First Use – Defines the number of days the account remains active after its first use or recharge.

o   ____days after Last Use – Defines the number of days the account remains active after its last use or recharge.

If you do not want to use these features, leave the fields blank.

 

5.      After clicking save_close Save & Close, you will see a confirmation screen announcing that a new account has been created.

Generate Vouchers

Since callback services are usually prepaid ones, auto-registered accounts are created with a zero balance. So to use the service, end users need to top up their accounts.

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

1.      Go to the Customers screen (the screen which contains a list of customers). It should resemble the screenshot below:

 

Generate vouchers

 

Open account generator

 

Fill in the vouchers info

 

2.      Next to the customer name, click on the Account https://demo.portaone.com/images/icons/no_accounts.gif or accounts Accounts icon (the one in the Accounts column), which will take you to the account management for that customer.

3.      Click on the Account Generator.

4.      Fill in the “Account generator” form:

o   Number of accounts – Number of accounts (callback cards) to be generated.

o   Account Role – Select the type of the account. Select Voucher from the list

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

 

Account Info tab

o   Opening Balance – The initial balance on the card. Type in 10 now.

o   Inactive - It is normal practice to generate all top-up cards as inactive so they cannot be misused before being sold to the dealer or end customer. You can always activate the whole batch of cards or an individual card later. If you plan to assign the cards to a distributor later on, the cards must be generated as inactive.

o   Generation method – Choose Random here; this will assign every account a unique, randomly-generated PIN.

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

o   ID length – All account IDs (PINs) will be numerical and of the specified length. In order to avoid problems with printing of top-up cards, 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.

o   Batch – Vouchers are grouped into batches for easy management. If a new batch name is provided in the text field, all accounts will be placed into a new batch with the given name. Otherwise, an existing batch should be selected from the list.

Products tab

o   Main Product – Choose the main product you have created for callback services.

Life Cycle tab

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

o   Specific Date – Identifies the date that the account expires.

o   ____days after First Use – Defines the number of days the account remains active after its first use or recharge.

o   ____days after Last Use – Defines the number of days the account remains active after its last use or recharge.

If you do not want to use these features, leave the fields blank.

 

5.      Click https://demo.portaone.com:442/images/icons/add.gif Generate; a confirmation screen will indicate that your information has been accepted.

6.      Click close Close to return to the account administration page.

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.

Testing

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.