AdminGuide:BasicConcepts:Extensions and SIP accounts/en

Return to AdminGuide:BasicConcepts

Extensions and SIP Accounts

Extensions are the primary telephone entities. An extension is a logical entity identified by its number, which is used as the identifier for all calls made by the extension and is the number dialed by other users who wish to contact the extension. Each extension has a number of attributes that define its permissions (for outgoing calls from the extension) and behavior (for incoming calls to the extension), as well as a few identity records (first and last name of the person to whom the extension is assigned, its organizational unit, and so on).

SIP accounts are "service" entities. They are the credentials (username and secret) that need to be configured on a SIP terminal (hardphone or softphone) so that it can authenticate to the PBX. Authentication is performed by the devices with two procedures: "SIP registration" and the execution of a new call.

The relationship between extensions and SIP accounts is one-to-many: each extension can be linked to multiple SIP accounts, which all behave as the same telephone entity in terms of identity, presentation, permissions, etc.

It is also possible to create a unique user for each extension; different permissions and roles can be granted to these users, in order to allow them to access their personal web page, perform some administrative or configuration tasks, use the KalliopeCTI applications (desktop or mobile), and invoke the available REST APIs. Please see the users and roles page for more details.

SIP registration and multiple devices per extension

SIP registration informs the PBX of the current location of a SIP account, i.e. the IP address and port (plus the protocol, e.g. UDP, TCP, TLS, or WebSocket) where the SIP account can be reached when the PBX needs to send it a message (i.e. an INVITE related to an incoming call). Registration is performed by the device at boot time (if the account is correctly configured) and then refreshed periodically before its validity expires; each periodic registration requires the repetition of the authentication procedure. The lifetime of the registration is established during the registration procedure itself. The device inserts a "Proposed Expiry" value (in seconds, usually defaults to 3600) in its REGISTER request; upon successful authentication, the PBX responds with a "200 OK" message that notifies the actual registration lifetime to the device, which must then send a new registration before the timeout expires (usually this new registration is performed at about half time, to allow for re-transmission in case of failures). If the registration timeout expires without the reception of a registration refresh, then the location of the account is discarded by the PBX and the calls destined to that account will fail due to it being "unavailable".

KalliopePBX keeps a single location for each configured SIP account; if the same SIP account is configured on multiple devices, all active at the same time, the periodic registration messages from each continuously change the location stored in KalliopePBX. A call destined to the SIP account is therefore presented only to the device that registered last. It is however possible to have multiple devices which behave as a single extension by defining one SIP account for each of the desired devices, and linking all these SIP accounts to the same extension.

Extension attributes and templates

Each extension has its own set of attributes that describe its identity and its telephony behavior. Some of these attributes are specific to each device and have to be individually configured, while others can be common to all or a subset of extensions. The former include the extension number itself (which must be unique within the PBX, or within each tenant for a multi-tenant PBX) as well as personal details such as first and last name, email address, and the personal PIN code used for authentication when accessing certain PBX services (e.g. call limitations and permissions and the failover actions to be executed on a failed call to the extension, based on the origin of the call and the cause of failure).

To ease the management of these common attributes, KalliopePBX introduces the concept of an extension template: a collection of attributes and settings that can be assigned to multiple extensions. Defining multiple templates (with different settings based on the extension type) reduces the number of settings that need to be specified for each single extension and helps quickly edit the same setting for all the extensions that share the same template simply by changing the value of the setting in the corresponding template.

In the configuration panel of each extension, it is possible to override any setting inherited from the associated template if a specific exception is needed. The overridden settings are not affected by changes to the template.

SIP Accounts attributes

As with extensions, SIP accounts have some specific attributes (mainly the username—which must be unique within the PBX—and the SIP secret), while others may be common to a "class" of accounts. These include supported transport protocols, media, or codecs, the authorized ACL, and others; SIP account templates can be used to define classes of SIP accounts with common settings, according to the same mechanism described for extensions.