SMS notifications configuration

Service providers can send SMS notifications to admins, customers, and resellers in two ways:

• Through a “traditional” SMS carrier via PortaSIP using the SMPP protocol.
• Via REST APIs offered by CPaaS providers like Twilio.

This handbook demonstrates how a service provider can configure sending SMS notifications to customers via the SMPP protocol. We assume that the Cloud PBX service and customers have already been created in the system.

Owl Telecom, a service provider, wants to enable SMS notifications for their cloud PBX customers in Spain. When an invoice becomes overdue, customers should receive a text message prompting them to make a payment and avoid service suspension. The messages will be sent from the phone number 3465558915.

Owl Telecom has an agreement with the vendor Lleida Networks, which will send the messages to mobile networks at a cost of $0.25/message.

When setting up SMS notifications, Owl Telecom’s admin must ensure the following:

1. Message delivery

   SMS notifications must reach all mobile networks in Spain – that is, phone numbers starting with the +34 country code. This ensures that every Cloud PBX customer in Spain will receive overdue-invoice reminders, regardless of their mobile carrier.

   The customer notifications are sent to the numbers stored under Alt. phone field of the customer record.
2. Message priority

   Set the priority of SMS notifications to low. Since Owl Telecom also offers messaging services – such as instant messages and standard SMS – a lower priority ensures that invoice reminders do not delay customer messages.

3. Number format

   Convert all destination numbers to the E.164 international format before sending SMS notifications. Customers may store their phone numbers in local formats, so this conversion guarantees that messages are routed correctly. For example, the local number 604555123 must be converted to +34604555123.

Before proceeding with the configuration, make sure you have the following information:

• A dedicated phone number from which SMS notifications will be sent to customers.
• Rate sheet provided by the vendor, specifying the prices for SMS notification termination.
• Username and password provided by the vendor for message authorization. These credentials are stored as vendor authorization data and linked to the connection used for message transmission. They will be needed in step 3.
• IP address of the vendor’s gateway that will handle the termination of SMS notifications to mobile networks.

1. Setup on the Configuration server web interface
2. Create two service policies
   1. Create a service policy for the transport protocol definition
   2. Create a service policy for vendor connection
3. Configure an SMS vendor
   1. Create a vendor tariff
   2. Create a vendor
   3. Define a vendor connection
4. Create a customer tariff
5. Create a product
6. Create an internal customer and account
   1. Create a customer
   2. Create an account
7. Configure SMS notifications for your customers

Ensure that the messaging service is enabled in the system.

For this, log in to the Configuration server web interface and perform the following steps:

1.1 To enable the messaging service type, go to BillingEngine > Global > ServiceTypes and set the MessagingService_Enabled option to Yes.

1.2 IMGate is a component of PortaSIP, which enables online messaging and message storage for offline users (so they can receive messages later). To enable sending of messages via IMGate, go to Web Cluster > Global > Notifications, and set the SendSmsVia option to IMGate.

1.3 In PortaSwitch, SMS notifications are sent from a special internal account, so an admin should create this account and assign the sender number to it (this will be done at step 6.2). This is the number customers will see when they receive SMS messages. The sender phone number must also be specified on the Configuration server web interface.

To configure the sender number for SMS notifications, go to Web Cluster > Global > Notifications, and set the phone number in the SendSmsFromPhone option, e.g., 3465558915.

Create a service policy that defines how PortaSIP routes and authorizes messages. Before sending a message, PortaSIP matches the recipient’s domain with the domain pattern in the service policies. The matching policy is then used to handle the message in a specific way (e.g., send it over SMPP or SIP).

1. Navigate to Service catalog > Service policies.
2. Click + Policy and fill in details in the General tab:
   • Service type – select Messaging.
   • Name – specify the name of the service policy, e.g., Internal service policy for SMS notifications.
   • Recipient domain pattern – specify a pattern according to which the service policy is selected. For this setup, specify “%”, which applies to all outgoing messages sent from your system. If you only allow sending notifications to a specific mobile operator, specify the %XXX% pattern (e.g., %34% for all mobile operators in Spain or %346% for Vodafone Spain). Then, when an SMS notification is sent to 3465551122, PortaSIP matches the pattern (346) to select the corresponding service policy and sends the message to the SMS vendor via the SMPP protocol.
   • Match priority – specify 3. This priority is lower than other types of messages, thus it prevents invoice reminders from delaying the customer messages.

     

3. Go to the Attributes tab and select Processing messages over SIP/SMPP.
   1. External routing – set Enabled. This will allow you to send SMS messages to external vendors.
   2. Outgoing AAA – set Enabled to enable outgoing message authorization and billing.
   3. Transport protocol – select SMPP from the list.
   4. Userpart E164 translation – set Enabled. This will convert all destination numbers to the E.164 international format before sending SMS notifications.

      

4. Click Save.

Create a service policy that defines the parameters for a specific vendor connection. For these parameters to apply, this service policy should be assigned to the corresponding vendor connection at step 3.3.

1. Navigate to Service catalog > Service policies.
2. Click + Policy and fill in details in the General tab:
   • Service type – select Messaging.
   • Name – specify the name of the service policy, e.g., Vendor service policy for SMS notifications.
   • Recipient domain pattern – leave this field empty.

     

3. Go to the Attributes tab and select Processing messages over SIP/SMPP to enable the following attributes:
   1. Bind as – select transceiver from the list to send messages.
   2. External routing – set Enabled.
   3. Heartbeat interval – specify how often (in seconds) the system should send keep-alive requests to make sure the connection is active, e.g., 2. Default 0 means no requests will be sent.
   4. Transport protocol – select SMPP.

      

4. Click Save.

Create a vendor that will deliver SMS notifications to customers.

This tariff will contain your SMS vendor’s transmission rates.

1. Navigate to Service catalog > Tariff.
2. Click +Tariff and fill in the tariff details:
   • Name – specify a descriptive name for the tariff, e.g., “Vendor tariff for SMS notifications”, which will be used within the system.
   • Currency – choose the currency in which the vendor charges you.
   • Service – select Messaging service.
   • Format – select E.164.
   • Applied to – choose Vendor.
   • Routing – turn on this toggle to enable the routing.
   • Define prices – select Per individual rate code.

     

3. Open the Rates panel in the “Vendor tariff for SMS notifications”.
   To add a rate, you need a rate code. Make sure that the needed rate codes have been added to the system. See more details on how to create rate codes in the Initial configuration of PortaBilling handbook.

You can add rates one by one or upload them from a file. To download the file sample with all the required columns, click Rate download on the toolbar, then open the notifications tab and download. To add a rate manually, click +Add and fill in the rate details:

• Rate code – type in a specific rate code directly or select it from the list, e.g., 34 for a Spanish destination.
• Rating mode – select Flat rate.
• Unit price – this is the price per SMS, e.g., $0.25/message.

  

To create a vendor:

1. Navigate to Infrastructure > Vendors.
2. Click +Add and fill in the vendor details:
   • Name – specify a descriptive name for the vendor (e.g., “Lleida Networks”).
   • Currency – leave the base currency unchanged.
   • Opening balance – this option is usually used when you migrate a vendor from a legacy system to PortaSwitch. Leave the value set to “0” here.
   • Billing period – choose a billing period for the vendor. The billing period defines how often the vendor will bill you, e.g., monthly.

     

3. To enable the digest authorization of outgoing messages, open the vendor page > General configuration > Authorization.
4. On the Authorization panel, click Add and enter the credentials provided by the vendor.
5. Click Save.

   

Create a vendor connection that represents a connection between PortaSwitch and the SMS vendor.

To create a vendor connection:

1. Go to the vendor page > Connections.
2. On the Connection list panel, click +Add and fill in the connection details:
   • Description – type a descriptive name for this connection. It will be displayed in the list of connections.
   • Service type – select Messaging service.
   • Type of connections –select SMPP.
   • Tariff – select the tariff created at step 3.1, e.g., “Vendor tariff for SMS notifications”.
   • Active – leave the toggle enabled to create this connection as active.
   • Enter the Gateway ID (the IP address of the vendor’s SMS gateway), e.g., 192.168.14.16.
   • Port – specify the port of the SMS provider’s gateway through which SMS will be delivered to this provider. The default SMPP port is 2775.
   • Select the created service policy for this connection at step 2.2, e.g., “Vendor service policy for SMS notifications”.

     

3. Go to Connection page > General configuration.
4. Select the vendor authorization from the Vendor authorization list that you have created at step 3.2.c, e.g., “Lleida SMS”.

   

This tariff includes rates for sending SMS from the internal account configured for sending SMS notifications (3465558915 phone number defined at step 1).

To create a customer tariff:

1. Navigate to Service catalog > Tariffs.
2. Click +Tariff and fill in the tariff details:
   • Name – type in a short name for the customer tariff; this name will be shown within the system, e.g., “Internal customer tariff for SMS notifications”.
   • Currency – select the currency for the internal account.
   • Service – select Messaging service.
   • Format – leave the default E.164 format.
   • Applied to – select Customer.
   • Managed by – select Administrator only.
   • Define prices – select Per individual rate code.

     

3. Click Save and Edit details.
4. Open the Rates tab in the “Internal customer tariff for SMS notifications”.
   To add a rate, you need a rate code. Make sure that the needed rate codes have been added to the system. See more details on how to create rate codes in the Initial configuration of PortaBilling handbook.

You can add rates one by one or upload them from a file. To download the file sample with all the required columns, click Rate download on the toolbar, then open the notifications tab and click download. To add a rate manually, click +Add and fill in the rate details:

• Rate code – type in a specific rate code directly or select it from the list, e.g., 34 for a Spanish destination.
• Rating mode – select Flat rate.
• Effective from – select Immediately.
• Unit price – this is the price per SMS. As this tariff will be assigned to an internal account, there’s no need to apply any charges, so you can set the rate to $0/message.

  

Create a product that will be assigned to the internal account for sending SMS notifications:

1. Navigate to Service catalog > Products.
2. Click +Add and fill in the product details:
   • Name – type in a short name for the product; this name will be used within the system, e.g., “Internal product for SMS notifications”.
   • Name visible to end users – leave the suggested name as is.
   • Product type – select Main product here.
   • Currency – choose a currency that 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 – leave the default Account self-care ACL.
   • Account role – select Universal to associate this product with the internal account.

     

3. Go to Product > Services and click Add a service to select services included in the product. To provide a messaging service, you need to include the Messaging service.

   

4. Once you save the product details, you need to configure usage charges:
   • On your product’s panel, click Charges, then click Usage charges.
   • On the Usage charges panel, click Add.
   • Fill in the required information:
     • Service – select Messaging service.
     • Node – select PortaSIP.
     • Access code – type SMPP.
     • Tariff – select the tariff that applies to the internal account, created at step 4, e.g., “Internal product for SMS notifications”.
     • Overdraft protection – leave these settings disabled.

       

Create an internal customer for sending SMS notifications.

1. On the navigation menu, select Sales, then select Customers.
2. On the Customer panel, click + Customer and fill in the customer details:
   • Balance control – select Postpaid.
   • Name – type a short name for the customer object; this will be used on the web interface, e.g., “Internal customer for SMS notifications”.
   • Currency – choose the currency for this customer.
   • Credit limit – assign a credit limit for the customer.
   • 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. As the customer is internal, select a customer class with invoicing disabled.
   • Billing period – choose a billing period for the customer.
   • Billing period time zone – choose a time zone in which the customer’s billing period will be closed and invoices will be generated.

     

Create the internal account for sending SMS notifications.

1. On your customer’s panel, click Accounts / DIDs.
2. On the Accounts tab, click + Account, and on the General tab specify the account details:
   • Type – select Credit.
   • Account role – select Universal.
   • ID – specify the phone number defined at step 1, e.g., 3465558915.
   • Service password – specify a secure, hard-to-guess password to prevent unauthorized access and protect your network from fraudulent call attempts.
   • Balance control – select Subordinate from the list.
   • Activation date – the date from which the account becomes usable.

     

3. Go to the Products tab and select the “Internal product for SMS notifications” product, created at step 5.

   

Now that you’ve configured the internal account that will be used to send SMS notifications, you can proceed with the notification setup.

SMS notifications are configured per Customer class. Refer to the Manage сustomer сlass тotifications handbook to enable the required SMS notifications for your customers.