AdminGuide:BasicConcepts:Extensions and SIP accounts

Back to AdminGuide:BasicConcepts

Extensions and SIP Accounts

The Extensions are the primary telephony entities. An Extension is a logical entity identified by its number, which is used as the identity for all the calls performed by the extension, and that is usually dialed by other users to contact the extension. Each extension has a number of attributes which define its permissions (e.g. for outgoing calls from the extension) and behaviour (e.g. for incoming calls to the extension), as well as a few identity records (e.g. first and last name of the person to whom the extenion is assigned, its organizational unit, and so on).

The SIP accounts are "service" entities, and can be seen just as the credentials (username and secret) that needs to be configured on a SIP terminal (hardphone or softphone) to allow it to authenticate to the PBX. Authentication is performed by the devices mainly in two procedures, which are the "SIP registration" and the execution of a new call.

The relationship between Extension and SIP account entities is 1-to-many, meaning that each Extension can have multiple associated 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 API. Refer to AdminGuide:BasicConcepts:Users and roles page for additional details.

SIP Registration and multiple device 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 a message - i.e. an INVITE related to an incoming call - to that account). 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 insert 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 which notifies the actual registration lifetime to the device, which then must ensure to send a new registration before the timeout expiration (usually this new registration is performed at about half time, to allow for retransmission 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 with cause "unavailable".

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

Extensions attributes and templates

Each extension has its own set of attributes which describe its identity and its telephony behaviour. Some of these attributes are specific and has to be configured explicitly whereas some other can be common to all or a subset of extensions. The former ones include the extension number itself (which must be unique within the PBX - or within each tenant in case of a multi-tenant PBX) as well as the personal details, such as first and last name or e-mail address, but also the personal PIN code used for authentication when accessing some PBX services; the latter ones include, as an example, call limits and permissions, or the actions to be performed on a failed call destined to the extension based on the origin of the call and the cause of failure.

To ease the administration of such common attributes, KalliopePBX introduce the concept of extensions template, which are a collection of attributes and settings that can be assigned to multiple extensions. Defining multiple templates (with different settings based on the type of the extensions) allows to reduce the number of settings which need to be specified for each single extension, and permits to quickly modify the same setting for all the extension which are based on the same template, just by changing the value of the setting in the related template.

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

SIP Accounts attributes

Like the extensions, SIP accounts have some specific attributes (mainly the username - which must be unique within the PBX - and the SIP secret) and some other which may be common to a "class" of accounts. These include the 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.