AdminGuide:BasicConcepts:Extensions and SIP accounts
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 (e.g. 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 stores 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 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 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. The latter include call limits 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 account 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; similarly to extensions, SIP account templates can be used to define classes of SIP accounts with common settings.
Extensions configuration
The extensions page contains the attributes of each KalliopePBX user. The main attribute that identifies each user is the telephone extension. If multiple devices (Accounts) are linked to the same user, these will share the telephone identity defined on this page. This means that, for example, all calls to an extension will be presented to all devices linked to the user, and all calls made from any of these devices will be made under the same telephone identity.
To configure extensions just open the operating menu and click on PBX > Extensions and Accounts.
To create a new extension proceed by clicking on "Add new extension".
- Enabled: Lets you disable an extension without losing its configuration.
- Extension: The internal phone number linked to the user.
- Name: Part of the name displayed to other users and shown in the phonebook.
- Last name: Part of the name displayed to other users and shown in the phonebook.
- Email address: Displayed in the phonebook.
- Mobile number: Displayed in the phonebook and used for Fork2Mobile and FastTransfer services.
- Service PIN: The code needed to access telephone services that require authentication (voicemail, switches, paging, electronic lock).
Account
Account
| ||
|---|---|---|
Parameter |
Description |
Value
|
| Add existing account | Lets you link an existing SIP account to the extension. | Account |
| Create account | Lets you create a new SIP account to link to the extension. | Account |
Voicemail
Voicemail
| ||
|---|---|---|
Parameter |
Description |
Value
|
| Create voicemail box | Lets you create a voicemail box for the account. | Yes / No |
| Email address | The address to which new message notifications are sent (optionally with audio file attached). | xxxxx@domain.yyy |
| Email notifications for new messages in voicemail box | If this option is enabled, the user will receive email notifications for new voicemail messages. | Yes / No |
| Forward audio messages as attachments | If this option is enabled, audio files containing recorded messages will be sent as email attachments. | Yes / No |
| Delete forwarded messages from Kalliope | If this option is enabled, forwarded messages will be deleted from KalliopePBX once the email is sent and will no longer be accessible from the phone and the KalliopeCTI mobile app. | Yes / No |
| Enabled | Lets you enable and disable voicemail without losing its settings and recorded messages. | Yes / No |
Local user settings
Local user settings
| ||
|---|---|---|
Parameter |
Description |
Value
|
| Create local user | Lets you create a local user for KalliopePBX in order to enable GUI or CTI access. | Yes / No |
| Enable GUI access | Allows the user to access the web GUI as a standard tenant user. The role of the user can be changed on the users management page. | Yes / No |
| Enable CTI access | Allows the user to use the KalliopeCTI clients. In order to use KalliopeCTI Pro or Phone, you will need to add the license from the users management page. | Yes / No |
| Username | Username used for logging into the GUI or KalliopeCTI. | Alphanumeric |
| Password | Password used for logging into the GUI or KalliopeCTI. | Alphanumeric |
Template
Template
| ||
|---|---|---|
Parameter |
Description |
Value
|
| Extension template | The template that contains the default parameters to use for the selected extension type. All attributes on the page will be changed to the default values, but it is possible to overwrite them if necessary. | Internal template |
Phonebook
Phonebook
| ||
|---|---|---|
Parameter |
Description |
Value
|
| Show in local phonebook | Choose whether or not the extension is shown in the local phonebook. | Yes / No |
| LDAP publishing mode | How the extension is published to LDAP, among the available options. The general LDAP publishing rule is set in the LDAP settings page. | Disabled / LDAP publishing rule / Show the number below / LDAP publishing rule applied to the extension below |
| Custom LDAP extension | Extension to which the LDAP publishing rule is applied. This field will only be shown if the option LDAP publishing rule applied to the extension below is selected. | Numeric |
| Custom LDAP number | Phone number linked to the user in the LDAP phonebook. This field will only be shown if the option Show the number below is selected. | Numeric |
| Organization | Used when publishing the phonebook (corresponds to the organization attribute when publishing to LDAP). | Alphanumeric |
| Department | Used when publishing the phonebook (corresponds to the organizationUnit attribute when publishing to LDAP). | Alphanumeric |
Service classes
Service classes
| ||
|---|---|---|
Parameter |
Description |
Value
|
| Standard outbound routing class | The routing class applied to the user when the electronic lock is disabled. If the unlock mode is set to Open, this will be the class applied to all calls. | Outbound routing class |
| Restricted outbound routing class | The routing class applied to the user when the electronic lock is enabled. If the unlock mode is set to Open, this will never be applied. | Outbound routing class |
Limits
Limits
| ||
|---|---|---|
Parameter |
Description |
Value
|
| Concurrent call limit | The maximum number of allowed concurrent inbound and outbound calls on all accounts linked to the extension. Setting this limit to 1 will prevent the extension from accessing services such as attended transfer as the call on hold waiting to be transferred will still be considered active. | Numeric (0 = no limit) |
| Busy level | The number of calls on all accounts linked to the extension after which the user is considered busy (the PBX will not present the call to the user's devices and answer with a 486 Busy Here SIP Message). Setting this limit to 1 for a single account will prevent inbound call notifications even if call waiting is enabled on the device. | Numeric (0 = no limit) |
Electronic Lock
Electronic lock
| ||
|---|---|---|
Parameter |
Description |
Value
|
| Unlock mode | The unlock mode for the extension.
Open – The electronic lock is always disabled. Code – The electronic lock can be disabled with the unlock code specified in the numbering plan. Password - The electronic lock can be disabled with the unlock code followed by the service PIN for the extension. |
Open / Code / Password |
| Unlock policy | The unlock policy for the extension.
Per call – The lock must be disabled before making each call. Automatically block after the number of minutes below – The lock will be automatically enabled after the specified duration. Unlocked until locked by the user – Once the lock is disabled, it will remain so until enabled again by the user. |
Per call / Automatically block after the number of minutes below / Unlocked until locked by the user |
| Unlock duration (sec.) | Length of time during which the lock is disabled. Only applicable if the unlock policy is Automatically block after the number of minutes below. | Numeric |
Group call pickup
Parameter |
Description |
Value
|
|---|---|---|
| Group membership | List of groups that this extension belongs to (calls to this extension can be picked up by any extension authorized to pick up calls from one of these groups). | Pickup groups |
| Pick up authorization | List of groups from which this extension is authorized to pick up calls (the extension can pick up calls to any extension that belongs to one of these groups). | Pickup groups |
Failover
Failover
| ||
|---|---|---|
Parameter |
Description |
Value
|
| Extension | Failover action on calls from an extension (including remote extensions). | |
| External | Failover action on calls coming from external numbers. | |
| Transfer | Failover action on call transfers. | |
| Timeout (sec.) | Length of time after which the failover action will be executed in case of no answer. | Numeric |
| No answer | A call is considered not answered after the timeout time has passed. | Hang up / Custom selection / Ask for selection / External number / Extension / Group / Queue / Checktime / IVR / Voicemail / MeetMe room |
| Occupied | The extension is considered occupied if it has reached the Busy Level set for the extension or if the terminal sends a 486 Busy Here SIP Response. | |
| Not available | The extension is considered not available if the terminal is not registered, unreachable at an IP level, or if the terminal sends a 480 Temporarily Unavailable SIP Response. | |
Account configuration
In the Account panel are defined the SIP credentials that can be used by a device to register and make/receive calls through the KalliopePBX. To these credentials are associated attributes to increase security and changes in the behavior of the KalliopePBX in terms of signaling and audio streams to be associated to a specific device. These attributes are defined at account level and not at extension level because two accounts associated to the same extension but to different devices may have different requirements.
Example: I can associate to an extension an account used on a physical phone and one used on a softphone. While for the physical phone I can use codecs with higher bandwidth consumption e.g. G711a for the softphone that is used for example in teleworking I can choose to use codecs such as G729 that optimize the use of bandwidth.
To configure accounts just open the operating menu and click on PBX > Extensions and Accounts. To create a new account, click on "Accounts" in the top bar and then on "Add SIP Account".
- Enabled: Lets you disable an account without losing its configuration.
- KCTI Mobile App: Lets this account be used with the KalliopeCTI mobile app, enabling push message sending for call signaling.
- Username: The username used for the SIP authentication of the device.
- Password: The password used for the SIP authentication of the device.
- Account template: The template that contains the default parameters to use for the selected account.
- Enable registration verification: When this setting is enabled, KalliopePBX will verify that the call setup request (SIP INVITE) comes from the same IP port as the registration request (SIP REGISTER).
- Enabled address: The IP address or subnet from which KalliopePBX accepts registration and call setup requests.
- Enabled subnet mask: Completes the ACL information on base IP for registration and call setup request.
- Enable NAT: When this setting is enabled, KalliopePBX will ignore IP addresses in the SIP and SDP headers and always answer from the IP address and port from which it received the request. This setting must be enabled only for devices that are one NAT behind KalliopePBX and do not solve the NAT traversal issue (through STUN / ICE / ALG SIP).
- Enable direct media: This setting lets you establish audio flows between two PBXs in direct visibility conditions (with no NAT). If this setting is enabled, services that require RTP flow monitoring (e.g. call recording, call transfer and parking with KalliopePBX service codes) will be disabled.
- Enable SRTP: This option lets you enable RTP encryption support. Since keys are exchanged within SIP / SDP messages in plaintext, it is best to use SRTP along with signaling encryption through TLS.
Outbound proxy settings
Outbound proxy settings
| ||
|---|---|---|
Parameter |
Description |
Value
|
| Outbound proxy address | Lets you set the IP address/hostname of the outbound proxy | Alphanumeric |
| Outbound proxy port | Lets you set the port of the outbound proxy | Numeric |
| Outbound proxy protocol | Lets you set the protocol used to communicate with the outbound proxy. You can only set protocols that have been enabled in the SIP settings | UDP / TCP / TLS / WS / WSS |
Transport settings
Transport settings
| ||
|---|---|---|
Parameter |
Description |
Value
|
| Enable UDP transport | Lets you enable the UDP transport protocol for SIP signaling. This setting is not available if UDP transport is not enabled in the SIP settings. | Yes / No |
| Enable TCP transport | Lets you enable the TCP transport protocol for SIP signaling. This setting is not available if TCP transport is not enabled in the SIP settings. | Yes / No |
| Enable TLS transport | Lets you enable the TLS transport protocol for SIP signaling. This setting is not available if TLS transport is not enabled in the SIP settings. | Yes / No |
| Enable WebSocket transport | Lets you enable the WebSocket (HTTP) transport protocol for SIP signaling. This setting is not available if WebSocket (HTTP) transport is not enabled in the SIP settings. | Yes / No |
| Enable secure WebSocket transport | Lets you enable the secure WebSocket (HTTPS) transport protocol for SIP signaling. This setting is not available if secure WebSocket (HTTPS) transport is not enabled in the SIP settings. | Yes / No |
Audio codec
Audio codec
| ||
|---|---|---|
Parameter |
Description |
Value
|
| Add codec | This section lets you select and organize the audio codecs usable by the account (which will be inserted into the SDP media description). | PCM a-law / G.722 / G.726 / G.729 / GSM / Opus / PCM u-law |
Video codec
Video codec
| ||
|---|---|---|
Parameter |
Description |
Value
|
| Add codec | This section lets you select and organize the video codecs usable by the account (which will be inserted in the SDP media description). | H.261 / H.263 / H.263+ / H.264 /VP8 |
Extension
Extension
| ||
|---|---|---|
Parameter |
Description |
Value
|
| Extension | The extension to which the SIP account is linked. | Extension |