Concept

Contacts

A contact contains information such as the name, the postal and email addresses, and others. A contact’s main purpose is to identify entities (resellers, customers, peers and subscribers) it is associated with.

A person or an organization may represent a few entities and it is handy to create a corresponding organization’s contact beforehand and use it repeatedly when creating new entities. In this case we suggest populating the External # field to distinguish between customers associated with the same contact.

Reseller	Contact	Customer	External #
Default	Rylic Longstaff	DTS	0007
Morning Times	0008
TelephOne	Clare Fenn	Lantern Co	—
Ike Leonard	City Bank	—

Reseller

Contact

Customer

External #

Default

Rylic Longstaff

DTS

0007

Morning Times

0008

TelephOne

Clare Fenn

Lantern Co

—

Ike Leonard

City Bank

—

Note that the only required contact field is email. For contacts associated with customers, it will be used for sending invoices and notifications such as password reset, new subscriber creation and others. A contact for a subscriber is created automatically but only if you specify an email address for this subscriber. It is mainly used to send notification messages, e.g. in case of a password reset.

Resellers

The reseller model allows you to expand your presence in the market by including virtual operators in the sales chain. A virtual operator can be a company without its own VoIP platform and even without a technical background, but with sales presence in a market. You define such a company as a reseller in the platform: grant limited access to the administrative web interface (the reseller administrator will only see his own customers, domains and billing profiles) and define wholesale rates for this reseller. Then, the reseller is free to operate under its own brand, make up its retail rates, establish the customer base and resell your services to its customers. The reseller’s profit is a margin between the wholesale and retail rates.

Let us consider an example:

You operate in Munich and provide residential and business services.
A company Cheap Call that has a strong presence in Frankfurt offers to resell your services under its own brand in this city.
You define wholesale rates for Cheap Call, such as calls to Argentina at €0,03.
Cheap Call defines its retail price and offers calls to Argentina at €0,04.
When one of Cheap Call’s subscribers makes a 5-minute call to Argentina, this subscriber will be charged €0,20.
You will get €0,15 revenue and Cheap Call’s profit will be €0,20 − €0,15 = €0,05.

A reseller usually uses dedicated IP addresses or SIP domain names to provide services. Also, a reseller can rebrand the self-care web interface for its customers and select languages per SIP domain that allows the reseller to operate even in multiple countries.

SIP Domain

A SIP domain represents an external Internet address where your subscribers register their SIP phones to make calls or send messages. The SIP domain also contains particular default configuration for all the subscribers registered with this SIP domain. A SIP domain can be a regular FQDN (e.g. sip.yourdomain.com) or a NAPTR/SRV record. Using IP addresses for SIP domains in production is strongly discouraged.

Additional SIP Domains

You can create as many SIP domains as required to satisfy your networking or marketing requirements, e.g.:

A dedicated SIP domain is suggested per CloudPBX customer.
A separate SIP domain may be dedicated to every whitelabel reseller.
Multiple SIP domains may be used to provide services in different countries or regions.
Multiple SIP domains may be used to brand your own services.

Contracts

A contract is a combination of a contact and a billing profile, hence it represents a business contract for your resellers and peering partners.

Contracts can be created in advance on the Reseller and Peering Contracts page, or immediately during creation of a peer or a reseller.

Note that the customer entity (described below) is a special type of the contract. A customer entity has an email and an invoice templates in addition to a contact and a billing profile.

Customers

A customer is a physical or legal entity whom you provide the VoIP service with and send invoices to. Here are the main features of a customer:

Contains the contact and legal information. For example, an address or an email address for invoicing.
Associated with a billing profile (to define fees per destination) and tracks the balance (used mostly for post-paid customers).
Contains a certain number of subscribers who actually use the service and whose calls appear in the customer’s list of CDRs.
Provides some default parameters for all its subscribers. For example, voice prompts and call restriction.

Here are two common examples of the customer model:

Residential and SOHO customers

With this service you provide your residential and SOHO customers with one or multiple numbers and offer the service on a post-paid basis.

For a residential customer you usually create one customer entity with one subscriber under it. A residential customer can register multiple devices with the same number thus having a convenient Viber or Skype-like service: any device can be used to make a call and all of them will ring simultaneously when there is an incoming call. At the end of the billing period, you send an invoice to the customer.

For SOHO customers you usually create multiple subscribers under the same customer and assign every subscriber a dedicated number to allow users make and receive calls. A common invoice will contain calls of all the subscribers.

Business customers with the Cloud PBX service

In this case you create a Customer and all the required entities under it to reflect the company’s structure: subscribers, extensions, hunt groups, auto-attendant menus, etc.

SIP Trunking

If a customer PBX can register itself with Sipwise C5, you create a regular subscriber for it and configure a standard username/password authentication. Multiple PBX users can then send and receive calls.

Legacy PBX devices that are not capable of passing the challenge-based authentication can be authenticated by the IP address. Optionally, every user of such a PBX can be authenticated separately by the FROM header and the IP address. For more details, refer to the Trusted Sources section.

Mobile subscribers

The pre-paid model works perfectly for mobile application users. In this case you generally create a single subscriber under a customer.

Pre-paid subscribers who use your calling cards

In this case you will most likely create a single subscriber under a customer, although multiple subscribers would work as well. In the latter case, they will share and top-up the common balance. Notice that the customer entity itself does not contain any technical configuration for the VoIP service authentication and instead contains other entities called subscribers, which do.

Subscribers

Every subscriber represents a SIP line or a SIP trunk. For example, in the residential services a subscriber entity is dedicated to every user. In the SIP trunking scenario, a subscriber can be used to authenticate all VoIP traffic from the remote PBX device.

In the following table logical subscriber types and their purpose are described.

Service	Subscriber Type	Purpose	Features
Residential	Regular subscriber	A regular VoIP service	Requires a DID number to receive calls from outside of your network
Enterprise (CloudPBX)	Pilot subscriber	A base number for the enterprise customer; Lists all extra numbers (aliases)	Configures the rest of customer subscribers in its self-care web interface
Extension	Extra numbers (DIDs, “implicit” extensions) for the enterprise customer	Can be dialed in different ways; The number configuration builds on top of the Pilot subscriber
PBX Group	Forwards incoming calls to multiple extensions	Ringing policy defines in which order the extensions will ring
SIP Trunk	Digest authentication	Dynamically registers a remote IP PBX device	Handles multiple users behind the IP PBX device
IP authentication	IP authentication of legacy IP PBX devices incapable of registering with the platform	Might require Trusted Subscriber and Trusted Source configuration

Service

Subscriber Type

Purpose

Features

Residential

Regular subscriber

A regular VoIP service

Requires a DID number to receive calls from outside of your network

Enterprise (CloudPBX)

Pilot subscriber

A base number for the enterprise customer; Lists all extra numbers (aliases)

Configures the rest of customer subscribers in its self-care web interface

Extension

Extra numbers (DIDs, “implicit” extensions) for the enterprise customer

Can be dialed in different ways; The number configuration builds on top of the Pilot subscriber

PBX Group

Forwards incoming calls to multiple extensions

Ringing policy defines in which order the extensions will ring

SIP Trunk

Digest authentication

Dynamically registers a remote IP PBX device

Handles multiple users behind the IP PBX device

IP authentication

IP authentication of legacy IP PBX devices incapable of registering with the platform

Might require Trusted Subscriber and Trusted Source configuration

Subscriber Aliases can provide Extra DIDs or extension numbers to a subscriber.

SIP Peerings

A SIP peering is your interconnection with the external VoIP or PSTN network. Usually, a VoIP service provider has at least a few termination partners to offer its subscribers calls to virtually any landline and mobile destination.

SIP peerings also enable incoming calls to your platform. For example, if you rent a pool of DID numbers from a SIP peer and offer them to your residential and business customers.

An interconnection with your termination partners and DID number providers can include multiple servers and enable both outbound and inbound calls, hence such a configuration is called a SIP peering group. You configure at least one SIP peering group for every partner and the main principle here is that all servers in a group terminate calls to the same set of listed destinations.

Any SIP peering group is associated with a contract for reconciliation and billing purposes and includes two main technical configurations:

Peering Servers Represent connections to/from your SIP peering’s network. The parameters include an IP address and/or a hostname of the remote part. For outbound calls, this is the destination address where to send calls to and for inbound calls it is an IP authorization of the remote server.
Outbound/Inbound Peering Rules Outbound rules define through which SIP peering group a call from a specific subscriber will be sent for termination to a specific destination.

The example below shows four SIP peering groups with different priorities, callee prefixes (actual destinations offered by this SIP peering) and callee / called patterns (fine-tuning which callee request URIs and caller URIs are allowed through this SIP peering group).

The figure shows how calls from premium subscribers can in the first place be routed through a dedicated SIP peering group unavailable to regular subscribers.

See the Routing Order Selection section for details about call routing.

Inbound rules allow filtering out incoming INVITE requests arriving from the corresponding SIP peering servers.