WHMCS Integration

This section contains instructions and a back-end module for integrating Centova Cast with WHMCS v5 or better. This will allow you to use WHMCS to provision and manage accounts in Centova Cast.

The Centova Cast module for WHMCS v5+ is located in:

/usr/local/centovacast/extra/billing/whmcs/

Prerequisites

The following prerequisites must be met to use Centova Cast with WHMCS:

Centova Cast must already be installed and configured.
WHMCS v5+ must be installed and configured. Familiarity with configuring WHMCS and setting up products/servers is required. Note that this module may work with earlier version of WHMCS, however v5 was used for development testing.

Please be sure that you are able to meet these requirements before proceeding.

Installation

WHMCS already bundles a copy of the Centova Cast integration module. To ensure that you have the latest and most compatible version of the Centova Cast WHMCS module, however, you should begin by copying the contents of /usr/local/centovacast/extra/billing/whmcs/ to your WHMCS directory's modules/servers/centovacast/ directory. For example:

cp /usr/local/centovacast/extra/billing/whmcs/* \
    /path/to/whmcs/modules/servers/centovacast/

Configuration

To configure WHMCS for use with Centova Cast, perform the following steps:

First, you need to configure WHMCS to access your Centova Cast server. To begin, login to WHMCS and click Setup > Products/Services > Servers.
Click Create New Group to create a new server group.
On the "Create New Group" page, enter Centova Cast in the Name field and click Save Changes.
Back on the "Servers" page, click Add New Server.
On the "Add New Server" page, fill out the following fields:
- Name
  Set this to the hostname of the machine on which Centova Cast is running.
- Hostname
  Enter the complete URL to your Centova Cast installation, for example:
  http://centovacast.yourdomain.com:2199
- IP Address
  Set this to the IP address of the machine on which Centova Cast is running. (Note that this is a WHMCS field and is not used by Centova Cast.)
- Type
  Select Centovacast from the list.
- Username
  In most cases, you should enter admin here. If you are not a Centova Cast licensee and you are instead using a Centova Cast reseller account from another hosting provider, you would enter your reseller account's username here.
- Password
  Enter your Centova Cast administrator password here. Again, if you are using a reseller account, you would enter your reseller account's password here.
- Secure
  Leave this checkbox unticked. Enabling it may cause connection errors.
All other fields can be ignored. When finished, click Save Changes.
Next, you need to configure a stream hosting product for your clients to purchase. Click Setup > Products/Services > Products/Services.
Click "Create a New Group".
On the "Create Group" page, enter Centova Cast in the Product Group Name field and click Create Group.
Back on the "Products/Services" page, click Create a New Product.
On the "Add New Product* page, fill out the following fields:
- Product Type
  Choose Hosting Account.
- Product Group
  Choose Centova Cast.
- Product Name
  Enter a name for the product you want to create, eg: "Centova Cast stream hosting package".
When finished, click Save Changes.
The product needs to be further configured to integrate correctly with Centova Cast and support all of the available functionality. The next several steps refer to the different tabs shown on in WHMCS on the "Edit Product" page.

On the Details and Pricing tabs, configure the WHMCS options as you desire. (These are not Centova Cast-specific.)
On the Module Settings tab, fill out the following fields:
- Module Name
  Set this to Centovacast. Changing this field will show the remainder of the options described below.
- Server Group
  Set this to Centova Cast (or whatever you called the server group when you created it in step 3 above).
- Account template name
  Enter the name of the Centova Cast account template to use for this package. You can create your account templates in Centova Cast by logging in as admin and clicking Management > Templates. This feature allows you to predefine completely custom configurations for each package.
- Max bit rate
  Specify the maximum bit rate (in kbps) for this stream. You may optionally leave this blank to use the value specified in the account template.
- Disk quota
  Specify the disk quota for this stream (which must be large enough to accommodate all of this server's configuration files, log files, and any media uploaded for the autoDJ). You may optionally enter unlimited to specify an unlimited quota, or leave this blank to use the value specified in the account template.
- Mount point limit
  Specify the maximum number of mount points the client may create (for ShoutCast v2 and IceCast streams). You may optionally leave this blank to use the value specified in the account template.
- Max listeners
  Specify the maximum number simultaneous listeners for this stream. You may optionally leave this blank to use the value specified in the account template.
- Data transfer limit
  Specify the monthly data transfer limit for this stream. You may optionally enter unlimited to specify unlimited data transfer, or leave this blank to use the value specified in the account template.
- Start server
  Set this to yes to automatically start the server after provisioning, or no if you want the user to start it manually before using it. Note that this only applies to non-autoDJ streams; if an autoDJ is enabled, it cannot be started until media is uploaded.
- Port 80 proxy
  Specify whether the port 80 proxy may be used with this stream (assuming port 80 proxy support has been enabled on the server). You may optionally leave this blank to use the value specified in the account template.
- AutoDJ support
  Specify whether the autoDJ may be used with this stream. You may optionally leave this blank to use the value specified in the account template.
- Max accounts
  This option is only used when creating a reseller account. Specifies the maximum number of client accounts that the reseller is permitted to create. You may optionally leave this blank to use the value specified in the account template.
- Max bandwidth
  This option is only used when creating a reseller account. Specifies the bandwidth limit for the reseller. See the bandwidth limit option in the administrator's manual for more information about the purpose of this value. You may optionally leave this blank to use the value specified in the account template.
This step is optional. If you would like to configure the WHMCS welcome email (which is sent to clients when a new Centova Cast account is ordered) to include information about the newly-created Centova Cast account, you may create custom fields for these values and Centova Cast will automatically fill them in with the appropriate values. These can then be used as merge fields in your WHMCS welcome email.

On the Custom Fields tab, under Add New Custom Field, enter the following:
- Field Name
  Enter one of the special field names supported by Centova Cast (listed below).
- Field Type
  Select Text Box.
- Admin Only
  Tick the Admin Only box. Don't forget to do this or the client will be prompted to fill out this field on the order form as if it were a configurable option. Leave the other options at their defaults.
You can create as many fields as you would like to use in your welcome emails. The supported field names, and their purposes, are described below:
- username
  Provides the username assigned to the stream account.
- ipaddress
  Provides the IP address assigned to the stream account. This may be particularly useful if using automatic IP address assignment.
- port
  Provides the port number assigned to the stream account. This may be particularly useful if using automatic port number assignment.
- sourcepassword
  Provides the source password assigned to the stream account. Note that due to a new restriction in ShoutCast v2, the source password is now dynamically generated by Centova Cast and will NOT match the administrator password for the account. Also note that WHMCS already provides a merge field to display the administrator password.
- servertype
  Provides the server type (ShoutCast, IceCast, etc.) for the stream account.
- sourcetype
  Provides the source type (ices, sc_trans, etc.) for the stream account.
- maxclients
  Provides the concurrent listener limit assigned to the stream account.
- maxbitrate
  Provides the bit rate limit assigned to the stream account.
- transferlimit
  Provides the data transfer limit assigned to the stream account, or 0 if unlimited.
- diskquota
  Provides the disk quota assigned to the stream account, or 0 if unlimited.
- mountlimit
  Provides the mount point limit for the stream account, or 0 if unlimited.
- resellerusers
  Provides the number of client accounts the reseller account is permitted to create, or 0 if unlimited.
- resellerbandwidth
  Provides the bandwidth limit for the reseller account, or 0 if unlimited.
After you have created one or more of these fields, you can add them to your welcome email templates as {$service_custom_field_fieldname}, where "fieldname" is the name of the field. For example, if you've created a custom field called "port", you can use {$service_custom_field_port} in your welcome email to display the port number.
This step is optional. If you would like to allow your users to "build their own" packages, and have WHMCS prompt the user for various stream limit options (bit rate, data transfer limit, etc.) and be able to set custom pricing for each option, you can set up Configurable Options in WHMCS for each of these values.

On the Configurable Options tab, select the configurable options group you'd like to assign to this product. If you have not yet created any Configurable Options, you can do so as follows:
1. First, click the Save Changes button to save your product as you'll need to leave the product editor to create your Configurable Options.
2. Next, click Setup > Products/Services > Configurable Options.
3. Click Create a New Group.
4. On the "Create a New Group" page, fill out the following fields:
  - Group Name
    Enter a descriptive name such as Centova Cast Configurable Options.
  - Assigned Products
    Select any Centova Cast products you've created. Click Save Changes.
The page will refresh and an Add New Configurable Option button will be displayed. Click the Add New Configurable Option button and follow the instructions below to create each of your Configurable Options.
- Configurable Listener Limit
  This allows the user to specify a custom listener limit. Enter Max listeners in the Option Name field to begin. Next, in the Add Option field, enter the number of listeners, then enter the extra fee for this number of listeners, and click Save Changes. Repeat this process for each listener limit you wish to offer.
- Configurable Bit Rate Limit
  This allows the user to specify a custom maximum bit rate (in kbps). Enter Max bit rate in the Option Name field to begin. Next, in the Add Option field, enter the bit rate, then enter the extra fee for this bit rate, and click Save Changes. Repeat this process for each bit rate you wish to offer. Note that Centova Cast treats this as a numeric value in kbps, and will strip any non-numeric characters out of this value before attempting to use it.
- Configurable Data Transfer Limit
  This allows the user to specify a custom data transfer limit (in MB per month). Enter Data transfer limit in the Option Name field to begin. Next, in the Add Option field, enter the limit (in MB), then enter the extra fee for this limit, and click Save Changes. Repeat this process for each limit you wish to offer. Note that Centova Cast treats this as a numeric value in megabytes, and will strip any non-numeric characters out of this value before attempting to use it.
- Configurable Disk Quota
  This allows the user to specify a custom disk quota (in MB). Enter Disk quota in the Option Name field to begin. Next, in the Add Option field, enter the quota (in MB), then enter the extra fee for this quota, and click Save Changes. Repeat this process for each quota you wish to offer. Note that Centova Cast treats this as a numeric value in megabytes, and will strip any non-numeric characters out of this value before attempting to use it.
- Configurable Mount Point Limit
  This allows the user to specify a custom mount point limit. Enter Mount point limit in the Option Name field to begin. Next, in the Add Option field, enter the number of mount points, then enter the extra fee for this mount point limit, and click Save Changes. Repeat this process for each mount point limit you wish to offer. Note that Centova Cast treats this as a numeric value, and will strip any non-numeric characters out of this value before attempting to use it.
- Configurable Reseller Bandwidth Limit
  This allows the user to specify a bandwidth limit (in kbps) for reseller accounts. See the bandwidth limit option in the administrator's manual for more information about the purpose of this value. Enter Max bandwidth in the Option Name field to begin. Next, in the Add Option field, enter the bandwidth limit (in kbps), then enter the extra fee for this bandwidth limit, and click Save Changes. Repeat this process for each bandwidth limit you wish to offer. Note that Centova Cast treats this as a numeric value in kbps, and will strip any non-numeric characters out of this value before attempting to use it.
- Configurable Reseller Client Account Limit
  This allows the user to specify a custom client account limit for reseller accounts. Enter Max accounts in the Option Name field to begin. Next, in the Add Option field, enter the number of accounts, then enter the extra fee for this account limit, and click Save Changes. Repeat this process for each account limit you wish to offer. Note that Centova Cast treats this as a numeric value, and will strip any non-numeric characters out of this value before attempting to use it.
- Configurable AutoDJ Support
  This allows the user to specify whether or not autoDJ support is desired for the account. Enter AutoDJ support in the Option Name field to begin. Next, using the Add Option field, enter the following options one-by-one:
  - 1|Yes, include autoDJ support
  - 2|No, I will provide my own live source
  You may customize the captions of the individual options. You may also optionally enter an extra fee associated with enabling or disabling autoDJ support. Finally, click Save Changes.
- Configurable Hosting Server ID
  This allows the user to specify a custom hosting server ID (from Management->Hosts). Enter Server in the Option Name field to begin. Next, in the Add Option field, enter the ID number for this host (from the Management->Hosts page) followed by a pipe (|) and any optional description you want to display for this hosting server. Then enter the extra fee (if any) for the use of this server, and click Save Changes. Repeat this process for each hosting server you wish to offer.
- Configurable Hosting Region ID
  This allows the user to specify a custom hosting region ID (from Management->Regions). Enter Server region in the Option Name field to begin. Next, in the Add Option field, enter the ID number for this region (from the Management->Regions page) followed by a pipe (|) and any optional description you want to display for this hosting region. Then enter the extra fee (if any) for the use of this region, and click Save Changes. Repeat this process for each hosting region you wish to offer.
This step is optional. If you would like to allow your users to upgrade or downgrade their streaming accounts, you can create multiple Centova Cast-based products in WHMCS and configure each one for upgrading/downgrading.

On the Upgrades tab, select the packages that you want to allow the client to upgrade or downgrade to from the current package.

IMPORTANT: Note that when upgrading or downgrading an account, Centova Cast will change ONLY the options shown on the "Module Settings" tab, excluding the "Account template name". If your WHMCS products use different account templates, any differences in those templates will NOT be applied to the upgraded/downgraded account. (This is a necessary technical limitation given that applying an account template to an existing stream would completely reset all of the account's settings to default values, including the stream name, email address, and so-on.)
This step is optional. If you would like to customize the information shown in the WHMCS client area for Centova Cast accounts, edit the file modules/servers/centovacast/client_area.html under your WHMCS installation directory.

The Centova Cast module should now be ready to use.

For more information about setting up products in WHMCS, please refer to the WHMCS manual.

Previous: iHost Integration

Section: Billing Integration

Next: Upgrading