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 (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.

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

Rubrica telefonica

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. Sbloccato finché l’utente lo blocca nuovamente – Il lucchetto una volta sbloccato deve essere bloccato esplicitamente dall'utente Per chiamata / Blocca automaticamente dopo il numero di minuti sottoindicato / Sbloccato finché l’utente lo blocca nuovamente Durata dello sblocco (sec.) Tempo dopo il quale l’interno viene bloccato. Applicabile solo se la politica di sblocco è Blocca automaticamente dopo il numero di minuti sottoindicato Numerico Prelievo di chiamata di gruppo Prelievo di chiamata di gruppo Parametro Descrizione Valore Gruppi di appartenenza Elenco dei gruppi autorizzati a prelevare le chiamate dirette all’interno (le chiamate dirette a questo interno possono essere prelevate da tutti gli interni con autorizzazione al prelievo su uno di questi gruppi). Gruppo di prelievo Autorizzazione al prelievo Elenco dei gruppi su cui l’interno è autorizzato a prelevare chiamate (l’interno può prelevare le chiamate dirette ad interni che hanno tra i gruppi di appartenenza un gruppo su cui l’interno è autorizzato al prelievo) Gruppo di prelievo Trabocchi Trabocchi Parametro Descrizione Valore Interno Azione di trabocco su chiamate provenienti da un interno (anche remoto) Esterno Azione di trabocco sulle chiamate provenienti dall’esterno Trasferimento Azione di trabocco sui trasferimenti di chiamata Timeout (sec.) Tempo alla scadenza del quale viene eseguita l’azione di trabocco configurata in caso di nessuna risposta Numerico Nessuna risposta La chiamata è considerata senza risposta alla scadenza del timeout Riaggancia / Selezione personalizzata / Chiedi selezione / Numero esterno / Interno / Gruppo / Coda / Controllo orario / IVR / Casella vocale / Stanza MeetMe Occupato L’interno è considerato occupato se è stato raggiunto il Busy Level impostato per l’interno oppure se il terminale invia il SIP Response 486 Busy Here Non disponibile L’interno è considerato non disponibile se il terminale non è registrato o non è raggiungibile a livello IP oppure se il terminale invia il SIP Response 480 Temporarily Unavailable Configurazione Account Nel pannello Account sono definite le credenziali SIP utilizzabili da un dispositivo per registrarsi ed effettuare / ricevere chiamate tramite il KalliopePBX. A queste credenziali sono associati attributi per incrementare la sicurezza e modifiche del comportamento del KalliopePBX in termini di segnalazione e flussi audio da associare ad uno specifico dispositivo. Questi attributi sono definiti a livello di account e non di interno perché due account associati allo stesso interno ma a dispositivi differenti possono avere requisiti differenti. Esempio: ad un interno posso associare un account utilizzato su un telefono fisico ed uno utilizzato su un softphone. Mentre per il telefono fisico posso utilizzare codec con maggior consumo di banda ad es. G711a per il softphone che viene utilizzato ad esempio in telelavoro posso scegliere di utilizzare codec quali il G729 che ottimizzano l’utilizzo della banda. Per configurare gli account basta aprire il menu operativo e cliccare su PBX > Interni e Account. Per creare un nuovo account procedere cliccando su "Account" nella barra in alto e successivamente su "Aggiungi Account SIP" Abilitato: Consente di disabilitare un account senza perderne la configurazione KCTI Mobile App: Consente di utilizzare questo account con l'app mobile KalliopeCTI abilitando l'invio dei messaggi push per la segnalazione delle chiamate Nome utente: Username utilizzato per l’autenticazione SIP del dispositivo || Alfa-numerico Password: Password utilizzata per l’autenticazione SIP del dispositivo || Alfa-numerico Template dell'account: Indica il template account contenente i parametri di default da utilizzare per la tipologia di interno prescelta Abilita verifica di registrazione: Quando questa opzione è abilitata il KalliopePBX verifica che la richiesta di setup di chiamata (SIP INVITE) provenga dallo stesso IP:porta da cui ha ricevuto la richiesta di registrazione (SIP REGISTER) Indirizzo abilitato: Indica l’indirizzo ip o la subnet da cui il KalliopePBX accetta richieste di registrazione e setup di chiamata Maschera di sottorete abilitata: Completa l’informazione della ACL su base IP per le richieste di registrazione e setup di chiamata Abilita NAT: Quando questa opzione è abilitata il KalliopePBX ignora gli indirizzi IP presenti negli header SIP e SDP e risponde sempre all'indirizzo IP e porta da cui ha ricevuto la richiesta . Questa opzione deve essere abilitata solo per dispositivi si trovano dietro un NAT rispetto al KalliopePBX e che non risolvono il problema dell’attraversamento NAT (tramite STUN / ICE / ALG SIP). Abilita direct media: Questa opzione consente di instaurare dei flussi audio tra 2 PBX che si trovano in condizioni di visibilità diretta (no NAT). Se questa funzione è abilitata i servizi che richiedono il monitoraggio del flusso RTP (ad es. registrazione chiamate, trasferimento di chiamata e parcheggio con codici di servizio del KalliopePBX) sono disabilitati. Abilita SRTP: Questa opzione consente di abilitare il supporto alla cifratura dei flussi RTP. Poiché lo scambio delle chiavi avviene all’interno dei messaggi SIP / SDP in plaintext è opportuno utilizzare SRTP insieme alla cifratura della segnalazione mediante TLS. (vedi Configurazione TLS/SRTP) Impostazioni di outbound proxy Impostazioni di outbound proxy Parametro Descrizione Valore Indirizzo dell'outbound proxy Consente di impostare l'indirizzo IP/hostname dell'outbound proxy da utilizzare Alfa-numerico Porta dell'outbound proxy Consente di impostare la porta dell'outbound proxy da utilizzare Numerico Protocollo dell'outbound proxy Consente di impostare il protocollo da utilizzare per comunicare con l'outbound proxy. È possibile impostare solamente protocolli abilitati nelle Impostazioni SIP UDP / TCP / TLS / WS / WSS Impostazioni di trasporto Impostazioni di trasporto Parametro Descrizione Valore Abilita trasporto UDP Consente di abilitare il protocollo di trasporto UDP per la segnalazione SIP. Questa opzione non è presente se il trasporto UDP non è abilitato nelle Impostazioni SIP Si / No Abilita trasporto TCP Consente di abilitare il protocollo di trasporto TCP per la segnalazione SIP. Questa opzione non è presente se il trasporto TCP non è abilitato nelle Impostazioni SIP Si / No Abilita trasporto TLS Consente di abilitare il protocollo di trasporto TLS per la segnalazione SIP. Questa opzione non è presente se il trasporto TLS non è abilitato nelle Impostazioni SIP Si / No Abilita trasporto Web Socket Consente di abilitare il protocollo di trasporto Web Socket (HTTP) per la segnalazione SIP. Questa opzione non è presente se il trasporto Web Socket (HTTP) non è abilitato nelle Impostazioni SIP Si / No Abilita trasporto Web Socket sicuro Consente di abilitare il protocollo di trasporto Web Socket sicuro (HTTPS) per la segnalazione SIP. Questa opzione non è presente se il trasporto Web Socket sicuro (HTTPS) non è abilitato nelle Impostazioni SIP Si / No Codec audio Codec audio Parametro Descrizione Valore Aggiungi codec In questa sezione è possibile selezionare e ordinare i codec audio utilizzabili dall'account (e che quindi verranno inseriti nella media description del protocollo SDP) PCM a-law / G.722 / G.726 / G.729 / GSM / Opus / PCM u-law Codec video Codec video Parametro Descrizione Valore Aggiungi codec In questa sezione è possibile selezionare e ordinare i codec video utilizzabili dall'account (e che quindi verranno inseriti nella media description del protocollo SDP) H.261 / H.263 / H.263+ / H.264 /VP8 Interno Interno Parametro Descrizione Valore Interno In questa sezione è possibile selezionare l'interno al quale associare l'account SIP Interno