Release

Search

Service providers can enable their customers to assign more products on their self-care portals (built in-house or by a third party) using the PortaBilling API. For example, when a PBX customer wants to add new phone lines for new employees or activate additional features such as call recording, they can do this via the self-care portal without contacting a service provider.

Service providers can control which products to show to a specific customer and how many instances of a specific product can be activated in total via a customer agreement. It includes the list of main and add-on products that the customer can use and the allowed number of assigned (used) instances for each product.

There are two options for adding new accounts under a customer via PortaBilling API:

  1. Adding new extensions (phone lines) by PBX customers while the corresponding accounts are generated automatically in PortaBilling. This feature is suitable for cloud PBX service and is available on our Cloud PBX Self-Care Portal, and service providers can also use it on their third-party or in-house developed self-care portals. It is possible to:
    1. Add new extensions one by one
    2. Upload new extensions in bulk (on the roadmap for our Cloud PBX self-care portal)
  2. Creating new accounts, suitable for generic products. If a service provider builds a self-care portal for services other than cloud PBX, they can use this feature. For example, it is used on the IoT&M2M portal, where a user can add new SIM cards (accounts).
    Currently, accounts are always created in an inactive state so that they can be checked and then activated later on by an administrator or an external application.

Note that service providers can also enable their customers to block/unblock a specific account (if the account is blocked by PortaBilling administrator, the customer cannot manage it). For example, a company occasionally hires external marketing specialists for seasonal sales campaigns. When a campaign ends and a specialist leaves, the company blocks their extension (the service provider doesn’t charge a subscription fee for the days when an account is blocked). They unblock it when a specialist starts working again.

Customer agreement

Link copied to clipboard

Customer agreement defines the set of main and add-on products that a specific customer can add to their service package via the service provider’s self-care portal (developed in-house or by a third party). To open the customer agreement on the PortaBilling UI, go to Customer > Finances > Agreements.

For example, a service provider has various products with different pricing for retail and enterprise customers in the system. The agreement for a customer includes only the products tailored for this customer segment, so, on the self-care portal, the customer can see only the allowed products. This means that the customer won’t be able to assign any other product in the system that is not meant for them, e.g., a retail customer won’t have the possibility to assign an enterprise product to their accounts.

Also, customer agreements allow service providers to limit the number of accounts with a specific product that a customer may have. These limits are configured according to the service provider’s business model. A service provider can offer packages that are activated per phone line, so a customer is charged for each package activation separately. Or a service provider can offer small businesses a service package that includes a bundle of the maximum allowed phone lines (along with additional features such as auto attendant) for a fixed price. In this case, a customer is charged a fixed price, no matter whether they activate the maximum allowed number of phone lines or less.

Let’s see how service packages corresponding to these two business models are configured and used:

  1. “$6 each phone line”
    1. The administrator:
      • creates a product that includes a $6 subscription;
      • adds the product to the customer agreement with no limitation on the number of accounts that can use this product (optionally, the administrator can limit the number of accounts to protect the customer from “bill shock”).
    2. The customer:
      • is allowed to assign this product to an unlimited number of accounts;
      • is charged $6 for each.
  2. “Up to 10 Cloud PBX phone lines for $30”
    1. The administrator:
      • creates a product without a subscription;
      • assigns the $30 subscription to the customer directly;
      • adds the product to the customer agreement and limits the number of accounts that can use this product to 10.
    2. The customer:
      • is allowed to assign this product to a maximum of 10 accounts;
      • is charged $30 when they sign up for this service package;
      • is not charged additionally when they assign this product to an account.

Configuration

Link copied to clipboard

Let’s say a service provider has a new PBX customer, ABC. ABC will manage their extensions via a service provider’s custom self-care portal.

To add the main and/or add-on products to a customer agreement, the PortaBilling administrator should perform the following steps:

  1. open the Customer > Finances > Agreement > click Main products or Add-on products > Add > select the main or add-on product from the list;
  2. in the Quantity field, specify the number of accounts each product can be assigned to.
    NOTE: "Unlimited" means that the product can be assigned to an unlimited number of accounts.

Example 1.

The service provider offers ABC the following products: “Auto attendant $6 per line”, “Cloud PBX $10 per line”, and “Call recording $4 per line” (add-on product). Each product includes the corresponding subscription ($5, $6, and so on).

The customer agreement includes these products with the Quantity option set to "Unlimited" since these products can be assigned to an unlimited number of extensions.

Agreements_main_products_1

Agreements_addon_products_1

Example 2.

The service provider offers ABC the cloud PBX package that includes 5 phone lines and 1 call recording add-on for $20 per month (charged via a subscription assigned to the customer directly).

Assign a subscription to customer directly

The customer agreement includes the main product “Cloud PBX up to 5 phone lines” and the add-on product “Call recording”. The number of extensions is limited via the Quantity option to 5 and 1 extensions correspondingly.

Example 2 - Add main products to the agreement

Example 2 - Add add-on products to the agreement

Adding new extensions in bulk

Link copied to clipboard

Service providers can use PortaBilling API to enable their PBX customers to add multiple extensions (phone lines) at once via third-party or in-house developed self-care portals. This feature is also on the roadmap for our Cloud PBX Self-Care Portal.

When PBX customers want to add multiple new extensions for their employees, they can upload the corresponding extensions in bulk from a .csv file. Then the portal uses the customer.upload_extensions method to pass the file to PortaBilling. All extensions are created in PortaBilling along with automatic creation of corresponding accounts.

Benefits
  • PBX customers can save time and effort by adding multiple extensions at once.
  • Service providers can make third-party or in-house developed self-care portals more convenient for PBX customers.

Example

Let’s say Panda Telecom is a service provider that offers an in-house developed self-care portal for their PBX customers that allows them to independently add new extensions and choose products.

ABC Company is a customer of Panda Telecom and Adam is their PBX administrator. Adam needs to add 12 extensions for the new hires. He can use the portal to add all 12 extensions in bulk by uploading a file with the corresponding extensions.

For this, the PBX admin needs to perform the following steps:

  1. Log in to the in-house developed self-care portal.
  2. Download the file template (with all available columns in the required order).
  3. Fill in the columns in the file.
    The mandatory columns are: “Extension number” and “Product”.

    SampleForBulk

    Extension number (mandatory) – this is the extension number, which should contain only digits.

    Name – the name of a user can be added.

    DID numbers – the PBX admin can specify a phone number that will be assigned to a specific extension (the phone number will be added as account alias). To specify several DID numbers, separate them with commas.

    Only the DID numbers that were previously provided to the customer can be assigned.

    Published – the “Y” (yes) value means that this extension can be dialed by name. “N” (No) is the default value.

    Email for notifications – this is the email address to which the user notifications will be sent.

    Timezone – the time zone of the extension.

    Product (mandatory) – the name of the product that will be assigned to the extension.

    Huntgroup – the PBX admin can specify the name of an existing hunt group where he wants to add the extension.

  4. Upload the .csv file with the list of extensions to the portal.

After the successful upload, Adam sees that the new extensions have been added and can be used by ABCs employees.

Naming conventions when allowing auto creation of accounts

Link copied to clipboard

The PortaBilling API methods add_customer_extension and upload_extensions allow PBX customers to create new extensions, while the corresponding accounts are generated automatically in PortaBilling. To ensure that accounts that are created automatically have unique IDs, the ID pattern of these accounts combines the internal customer ID and the extension number (if a customer creates an auto attendant, then the sequence number is used).

Let’s consider an example. Say ABC customer needs to create:

  • the auto attendant and
  • an extension for a new employee, John Doe

To create the auto attendant, the PBX customer opens their self-care portal (built by the service provider or by a third party), adds the auto attendant, and assigns the “Auto attendant” product to it. The account with a universal account role and corresponding assigned “Auto attendant” product is automatically generated in PortaBilling. The account ID will have the following format:

ph${i_customer}aa{num}, where:

  • i_customer – internal ID of a customer record in PortaBilling;
  • num – a sequence number of an auto attendant, created by the customer.

So, the account with the “Auto attendant” product created for the customer with i_customer= 46170 in PortaBilling has an ID ph46170aa1.

As soon as the PBX customer assigns a DID number 12094555948 to the auto attendant, this number is assigned as an alias to the ph46170aa1 account in PortaBilling.

Next, the PBX customer creates an extension for John Doe (e.g., 4665) and assigns the “Cloud PBX” product to it. The account with a universal account role and corresponding assigned product is automatically generated in PortaBilling. The account ID will have the following format:

ph${i_customer}x${extension_id}, where:

  • i_customer – internal ID of a customer record in PortaBilling;
  • extension_id – the number of the extension, created by the customer on the self-care portal.

So, the account (corresponding to the extension created on the self-care portal) for the customer with i_customer= 46170 is created in PortaBilling with the following ID: ph46170x4665.

On this page

Release
What's new
Admin manuals
Handbooks
API
UI help
Search