Update extensions.rst (#253)

* Update extensions.rst

Updated document according to version 5.3, but some information should be verified.

source/accounts/extensions.rst

@@ -1,118 +1,380 @@
+.. Title:: Extensions
+
 ************
 Extensions
 ************
 
-**Extensions** define the information needed for an endpoint such as a hard phone, soft phone or some other device to connect to the SIP server. The extension is the SIP username and the password is the secret used for authentication. The domain name servers (DNS) to purposes it, locates the server to register to and is the realm that determines which domain the endpoint is registering to.
+**Extensions** define the necessary information for an endpoint, such as a hard phone, soft phone, or other devices, to 
+connect to the SIP server. The extension serves as the SIP username, and the password is the secret used for 
+authentication. The domain name system (DNS) locates the server to register with and determines the realm, which 
+specifies the domain the endpoint is registering to.
+
+************************************************
+Basic Settings
+************************************************
 
+Overview
+++++++++++++
+* **Extension**
 
-.. image:: ../_static/images/accounts/fusionpbx_accounts_extensions.png
-        :scale: 60%
+   Accepts alphanumeric values for the extension. The default configuration allows for 2–7 digit extensions. Alphanumeric 
+   extensions combine letters and numbers, providing flexibility for various use cases. They can help identify departments 
+   or roles, such as SALES1 or SUPPORT2, and personalize extensions for employees, like JOHN1 or SARAH2.
 
+* **Range**
 
-Basic Settings
-~~~~~~~~~~~~~~~~
-
-*  Extension 	
-    Enter the alphanumeric extension. The default configuration allows 2 - 7 digit extensions.
-*  Number Alias 	
-    If the extension is numeric then number alias is optional. The primary purpose of this field is when the extension is not a number then the number alias is required. Note a numeric extension and number alias does not currently work.
-*  Range 	
-    Enter the number of extensions to create. Increments each extension by 1.
-*  Voicemail Password 	
-    Enter the numeric voicemail password here.
-*  Account Code 	
-    Used with billing systems if you don't have a billing system then its optional.
-*  Effective caller ID Name 	
-    Internal Caller ID name
-*  Effective Caller ID Number 	
-    Internal caller ID number usually set to the extension number.
-*  Outbound Caller ID Name 	
-    Used by the outbound route for external caller ID name. Business or Organization typically is set here.
-*  Outbound Caller ID Number 	
-    Used by the outbound route for external caller ID number here. Business or Organization number goes here.
-*  Emergency Caller ID Name 	
-    This is used when calling out to an emergency service like 911.
-*  Emergency Caller ID Number 	
-    This is used when calling out to an emergency service like 911.
-*  Directory Full Name 	
-    The first and last name used in the directory. You can call that directory with *411
-*  Directory Visible 	
-    Select whether to hide the name from the directory.
-*  Directory Extension Visible 	
-    Select whether announce the extension when calling the directory.
-*  Limit Max 	
-    Set max number of outgoing calls for this user.
-*  Limit Destination 	
-    Set the destination to send the calls when the max number of outgoing calls has been reached.
-*  Voicemail Enabled 	
+   This option is only visible when creating an extension and allows for you to create a block of extensions at once. 
+   Enter the number of extensions to create, with each subsequent extension incrementing by 1.
+
+* **Voicemail Password**
+
+   Enter the numeric voicemail password here.
+
+* **Account Code**
+
+   Used with billing systems. If you don’t have a billing system, this field is optional.
+
+* **Effective Caller ID Name**
+
+   The internal caller ID name that will be displayed on other internal phones when receiving a call from this extention. 
+
+* **Effective Caller ID Number**
+
+   The internal caller ID number, typically set to the extension number. This number will be displayed on other internal 
+   phones when receiving a call from this extension.
+
+* **Outbound Caller ID Name**
+
+   Used by the outbound route for the external caller ID name. Typically, the business or organization name is set here. 
+   Note that your SIP provider may or may not allow this name to be transmitted to the receiving party.
+
+* **Outbound Caller ID Number**
+
+   Used by the outbound route for external caller ID number. Typically, the business or organization number is set here.
+
+*  **Emergency Caller ID Name**
+
+    This is used when calling emergency services, like 911.
+
+*  **Emergency Caller ID Number**
+
+    This is used when calling emergency services, like 911.
+
+* **Directory Full Name**
+
+    The first and last name used to populate the directory. You can access the directory by dialing *411.
+
+* **Directory Visible**
+
+    This setting determines whether the extension number will be hidden or visable to the directory. 
+
+* **Directory Extension Visible**
+
+    This setting determines whether the extension number will be announced to the caller when searching for a user 
+    in the directory.
+
+* **Max registrations**
+    
+    Set the maxium number of registrations for this user. 
+
+* **Limit Max**
+
+    Set the maximum number of outgoing calls for this user.
+
+* **Limit Destination**
+
+    Set the destination for calls when the maximum number of outgoing calls have been reached. The default setting 
+    is :code:`!USER_BUSY`. 
+
+*  **Voicemail Enabled** 
+   	
     Enable or disable voicemail for this extension.
-*  Voicemail Mail To 	
-    The email address for sending voicemail to email.
-*  Voicemail File 	
-    Select whether to send the voicemail as an attachment or as a link in the email.
-*  Voicemail Keep Local 	
-    Choose whether to keep the voicemail in the system after sending the email notification.
-*  Missed Call 	
-    Set the missed call to true and set the email address if you want to receive an email for missed calls that were routed through the dialplan to and was not answered by the extension.
-*  Toll Allow 	
-    Enter the toll allow value here. (Examples: domestic,international,local) This can be set to any name you want it sets a variable that can be a condition on the outbound routes.
-*  Call Timeout 	
-    Set the timeout for the call ringing.
-*  Call Group 	
-    You can define any call group you want the following groups are examples: sales, support, billing. These are used for group intercept or calls can be sent to the call group.
-*  Call Screen 	
-    If set will ask the caller to identify themselves. Their response will be recorded and offered to the person receiving the call.
-*  Record 	
-    Whether to record local, inbound, outbound, or all calls that were sent directly to this extension.
-*  Hold Music 	
-    Select music or ring tones that will be used for music on hold for this extension.
-*  Context 	
-    The context is set by default to match the domain name or IP addres. It is usually correct by default and doesn't need to be changed in most cases.
-
-*  Enabled
-    Extension enabled or disabled.
-*  Description
-    A description for the extension.
+
+*  **Voicemail Mail To** 	
+
+    The email address for sending voicemail notifications. Multiple email addresses can be entered, separated by commas. 
+
+*  **Voicemail File** 	
+
+    Select whether to send the voicemail as an attachment (wav file) or as a link in the email. 
+
+*  **Voicemail Keep Local** 	
+
+    Choose whether to keep the voicemail in the system after sending the email notification. 
+    Selecting "false" will delete the voicemail after it is sent.
+
+*  **Missed Call**
+
+    This option sends an email for each missed call. To enable this option, you must enter an email address.
+
+*  **Toll Allow** 	
+
+    Enter the toll allow value here. (Examples: domestic,international,local) For example, if you set Toll Allow 
+    to "domestic," the extension will only be allowed to make domestic calls, while calls to international or other 
+    restricted destinations would be blocked. You can create custom values such as "domestic," "international," 
+    or "local" depending on the dialing restrictions or rate plans you want to enforce for that extension.
+
+*  **Call Timeout** 	
+
+    This setting defines the amount of time the system will wait while an extension rings before considering 
+    the call to be unanswered. This timeout is typically used to determine how long the system will attempt to 
+    connect a call to an extension before it moves on to the next step in the dial plan, such as going to voicemail 
+    or routing the call elsewhere.
+
+*  **Call Group** 	
+
+    When a call is routed to a call group, it will be directed to all extensions within that group. This can be 
+    useful for handling calls that need to be answered by multiple people within the same department. For example, 
+    if you route calls to the "sales" group, all extensions assigned to the "sales" call group will ring when a call 
+    is directed to that group.
+
+*  **Call Screen** 	
+
+     enables a feature where the system prompts the caller to identify themselves before the call is connected to 
+     the recipient. When this option is enabled, the caller is asked to state their name or provide an identifying 
+     message, which is then recorded. The recorded response is presented to the person receiving the call, allowing 
+     them to decide whether to accept or reject the call based on the caller's identity. This feature can be 
+     particularly useful for businesses that want to screen calls and avoid unwanted or unknown callers.
+
+*  **Record** 	
+
+    The Record setting determines whether calls made to or from a specific extension should be 
+    recorded. You can configure it to record:
+
+    * Local calls: Calls made internally between extensions.
+    * Inbound calls: Calls received from external sources.
+    * Outbound calls: Calls placed to external destinations.
+    * All calls: A setting that records every call, regardless of whether it's inbound, outbound, or local.
+  
+    This feature is useful for tracking, monitoring, or maintaining records of conversations for compliance, 
+    quality assurance, or other purposes. The recording typically results in audio files stored in the system, 
+    which can be accessed or managed as needed.
+
+*  **Hold Music** 	
+
+    This setting allows you to select the music or ringtone that will be played to callers who are placed on 
+    hold by this extension. This feature helps enhance the caller experience by providing audio while they wait, 
+    preventing silence and creating a more professional impression.
+
+    You can choose from a variety of pre-uploaded music tracks or ring tones, or you may upload custom audio 
+    files to be used as hold music. This music plays during call hold periods until the call is resumed by the 
+    extension user or transferred to another destination.
+
+   **Language**
+
+    The Language setting allows you to select the preferred language, voice, and dialect for 
+    the extension. This setting impacts various aspects of the system, such as voicemail prompts, 
+    IVR (Interactive Voice Response) menus, and other voice-related features.
+   
+   **Type**
+
+    This setting determines the registration method for an extension or device.
+
+    * Default: This option enables registration for the extension, meaning it allows the 
+      device (e.g., hard phone, soft phone) to register with the SIP server, making it active and able to 
+      send/receive calls.
+
+    * Virtual: This option disables registration and creates a virtual extension, which does not require 
+      a physical device to register. This can be useful for extensions that don’t need to be tied to a specific 
+      device, such as for voicemail, call forwarding, or other non-registered use cases.
+
+    In summary, Default is used for regular extensions that need SIP registration, while Virtual is used for 
+    extensions that don’t require direct device registration but may still perform other functions.
+
+    **Domain**
+
+    * This setting refers to the domain name or IP address associated with the SIP server or PBX system. This 
+      setting is used to identify and route calls for a particular domain within the system.
+
+    When you select a domain, it determines which domain the extension or device is registering with, and 
+    it is crucial for routing calls within multi-domain environments.
+
+*  **Context** 	
+
+    * The Context setting in FusionPBX defines the logical grouping or scope of call processing for a specific 
+      extension or device. It determines which set of rules or configurations should be applied to the calls 
+      coming from or going to that extension.
+
+    By default, the Context is set to match the domain name or IP address of the system. This means that 
+    calls associated with that domain or IP will use the default set of rules defined for that domain context.
+
+*  **Enabled**
+
+    * This setting determines whether a specific extension is active or inactive. 
+      When set to Enabled, the extension is active and can make or receive calls, register with the SIP server, and 
+      function normally within the system.  When set to Disabled, the extension is inactive. It will not be able to 
+      make or receive calls, and it will not register with the SIP server. This is useful when temporarily deactivating 
+      an extension without deleting it from the system.
+
+     This setting allows administrators to quickly disable an extension without losing its configuration, which 
+     can be useful for maintenance, testing, or temporarily removing access for a user.
+
+*  **Description**
+
+    This setting allows you to add a custom label or note to an extension. This is typically used 
+    for identifying the extension's purpose or the person associated with it.
+
+    For example, you might use this field to provide details such as:
+
+    * The name of the person using the extension (e.g., "John Doe's Desk Phone").
+    * The department or role the extension serves (e.g., "Sales Team Extension").
+    * Special instructions or notes about the extension.
+   
+    The Description is helpful for administrators to manage and quickly identify extensions, especially in larger systems 
+    with many extensions. It does not affect the functionality of the extension itself; it’s purely for organizational purposes.
+
 
 
 Advanced Settings
-~~~~~~~~~~~~~~~~~~~
-
-Advanced settings in extensions. Be sure to know what and why you are changing these settings or you will risk causing issues for the extention.
-
-.. image:: ../_static/images/accounts/fusionpbx_accounts_extensions_advanced.png
-        :scale: 100%
-
-*  Auth ACL
-    Advanced auth acl uses.
-*  CIDR
-    Advanced cidr uses.
-*  SIP Force Contact
-    Choose whether to rewrite the contact port, or rewrite both the contact IP and port.
-*  SIP Force Expires
-    To prevent stale registrations SIP Force expires can override the client expire.
-*  MWI Account
-    MWI Account with user@domain of the voicemail to monitor.
-*  SIP Bypass Media
-    Choose whether to send the media stream point to point or in transparent proxy mode.
-*  Absolute Codec String
-    Absolute Codec String for the extension.
-*  Force ping
-    Use OPTIONS to detect if extension is reacheable.
-*  Domain
-    The domain the extension is currently saved on.
-*  Dial String
-    Location of the endpoint.
+==================
+
+.. warning::
+
+   Exercise caution when modifying advanced settings within extensions. Ensure you fully understand the purpose and impact of any changes, as incorrect configurations can disrupt the extension's functionality. Always back up your settings before making adjustments.
+
+Advanced
+==========
+
+    **Auth ACL**
     
+    This setting is used to define an Access Control List (ACL) for authentication. This ACL is a set of rules that control which IP addresses or subnets are allowed to register or authenticate with the system. It helps enhance security by limiting access to the FusionPBX system based on specific network criteria.
+
+    **CIDR**
+    
+    The CIDR (Classless Inter-Domain Routing) setting in FusionPBX is used to specify IP address ranges in a compact, efficient 
+    format. CIDR notation is commonly used to define network subnets and control access to the system based on IP ranges.
+
+    In simpler terms, CIDR allows you to define a range of IP addresses by combining an IP address with a subnet mask. For 
+    example, a CIDR block like 192.168.1.0/24 refers to all IP addresses from 192.168.1.0 to 192.168.1.255.
+
+    When configured in FusionPBX, this setting can be used to define which IP ranges (e.g., subnets or individual addresses) are allowed to connect 
+    to the system or specific features.  Network Segmentation: You can use CIDR to manage different parts of your network 
+    and apply different rules for different segments.  For example, if you want to restrict access to your FusionPBX server to only certain subnets, you would specify those IP ranges in CIDR notation under this setting.
+
+    The CIDR setting is typically used by advanced users or network administrators who need to configure more precise network 
+    security or routing rules.
+
+    **SIP Force Contact**
+    
+    The SIP Force Contact setting in FusionPBX controls how the SIP contact header (which includes the IP address and port) is 
+    handled when the SIP message is processed. This is particularly useful in environments with Network Address Translation (NAT) 
+    or other network configurations that require specific handling of contact information.
+
+    The options are as follows:
+
+    * Rewrite Contact IP and Port: This option rewrites both the IP address and the port in the SIP contact header. It's 
+    typically used when you want to force the system to always use a specific IP address and port combination for communication, 
+    regardless of the original contact information in the SIP message. This setting is useful in cases where SIP devices behind 
+    NAT or firewalls need a fixed contact IP and port for consistent communication.
+
+    * Rewrite Contact IP and Port 2.0: This may be a variation or update to the first option, specifically for newer configurations 
+    or additional handling of contact headers. It's likely designed for improved SIP communication in more complex network 
+    environments or to handle newer versions of SIP-related standards or devices.
+
+    * Rewrite TLS Contact Port: This option specifically targets SIP communication over TLS (Transport Layer Security). TLS is 
+    used for encrypted SIP communication, and this setting allows you to control the port used for TLS-secured SIP connections. 
+    This can be important in environments where SIP over TLS is required for security reasons, and the contact port needs to 
+    be explicitly defined.
+
+    In summary, the SIP Force Contact setting allows you to control how contact information is rewritten for SIP 
+    communication, providing flexibility in handling SIP devices, especially when dealing with network configurations that 
+    require precise management of IP addresses and ports.
+
+    **SIP Force Expires**
+
+    This setting is used to control the expiration time for SIP registrations and to prevent stale or 
+    outdated registrations from being maintained.
+
+    SIP Force Expires allows the server to override the expiration time that the client (SIP device or endpoint) has set 
+    for its registration. This ensures that the registration is refreshed more frequently, even if the client has specified 
+    a longer expiration time.
+
+    The main purpose of this setting is to ensure that SIP registrations do not become stale. If a SIP device does not refresh 
+    its registration within the expected time frame, it could lead to missed calls or communication issues. By setting SIP Force 
+    Expires, the server can enforce a stricter refresh rate, preventing any stale registrations from persisting.
+
+    In practice, this setting is particularly useful in dynamic environments where SIP clients may be behind 
+    NAT (Network Address Translation), or in cases where SIP devices may not always adhere to optimal registration refresh 
+    intervals. By forcing a specific expiration time, FusionPBX can ensure that SIP registrations are kept up-to-date, maintaining 
+    better communication reliability and preventing potential connectivity issues.
+
+    **MWI Account**
+
+    This setting is used to specify the Message Waiting Indicator (MWI) account that will monitor the 
+    voicemail box for a particular extension.
+
+    MWI (Message Waiting Indicator) is a feature used in SIP systems to indicate whether there are unread voicemail messages. 
+    This is typically represented by a blinking light or a visual indicator on the phone or device, signaling that the user has 
+    new voicemail.
+
+    The MWI Account setting allows you to define the specific voicemail account that will be monitored for message waiting 
+    notifications. The value entered in this setting follows the format user@domain, where:
+
+    * user is the voicemail box (or extension) to be monitored.
+    * domain is the domain associated with the system, often matching the SIP server's domain or the PBX domain.
+
+    For example, if the extension 1001 has voicemail, and the domain of your system is example.com, you might set the MWI 
+    Account to [email protected].
+
+    **SIP Bypass Media**
+
+    This setting determines how the media stream (audio or video) is handled during a call.
+
+    * Bypass Media: If enabled, the media stream (RTP packets) is sent directly between the 
+      endpoints (e.g., phones or devices), bypassing the PBX. This reduces the load on the PBX server and can improve 
+      performance by minimizing latency, especially in systems with high call volumes.
+
+    * Proxy Media: If bypass media is not enabled, the PBX acts as a proxy for the media stream. This means the media 
+      flows through the PBX server, allowing features like call recording, transcoding, or NAT traversal to be applied. 
+      This mode is necessary for certain advanced functionalities but increases the server's resource usage.
+
+    **Absolute Codec String**
+
+    This setting allows you to specify a fixed list of audio codecs for the extension.
+
+    When this setting is configured, the PBX will enforce the use of only the codecs listed in the string for calls involving 
+    this extension. This can be useful in scenarios where specific codecs are required for compatibility, performance 
+    optimization, or integration with external systems.
+
+    For example:
+
+    If your network requires low-bandwidth codecs, you might specify G729 or G723.
+    For higher-quality audio, you might specify PCMU, PCMA, or G722.
+    The format of the string should list the codecs in order of priority, separated by commas (e.g., G722,PCMU,PCMA).
+
+    **Force ping**
+
+    This setting determines whether the PBX will send SIP OPTIONS messages to an extension to verify its reachability.
+
+    When enabled, the PBX periodically sends these messages to the extension to confirm that it is still registered and 
+    responsive. This can help detect and handle situations where an extension becomes unreachable due to network issues or 
+    other disruptions.
+
+    This setting is particularly useful in environments where maintaining real-time awareness of endpoint status is critical, 
+    such as call centers or systems with high availability requirements. If disabled, the PBX will not actively check the 
+    extension's status using SIP OPTIONS messages.
+
+    **Dial String**
+
+    This setting defines the SIP URI or path used to locate the endpoint for this extension.
+
+    This value specifies how the PBX should contact the extension during a call. It typically includes information like the 
+    protocol (e.g., SIP), the username, and the domain or IP address of the endpoint.
+
+    For example, it might look like sofia/internal/[email protected], indicating the protocol, the extension (1001), and 
+    the domain to which the PBX will route the call.
+
+    This setting is automatically generated in most cases and usually doesn’t require manual modification unless there is a 
+    specific need for custom routing or advanced configurations.
 
 Caller ID Select
-~~~~~~~~~~~~~~~~
+==========
 
-**Extension Caller ID input type select**
+    **Extension Caller ID input type select**
 
-If you want extension caller ID name and number to be a input type text then make sure permission outbound_caller_id_select assigned to groups in Groups Manager.  By default outbound_caller_id_select is not assigned to any user groups.
+    If you want extension caller ID name and number to be input type text, make sure permission outbound_caller_id_select is assigned to groups in Groups Manager. By default, outbound_caller_id_select is not assigned to any user groups.
 
 
-**Extension Caller ID input type select**
+    **Extension Caller ID input type select**
 
-If you want a select option for caller ID then you would want to assign outbound_caller_id_select permission to groups of your choice using Group Manager and define Caller ID information in Dialplan Destinations.
+    If you want a select option for caller ID, you would assign outbound_caller_id_select permission to groups of your choice using Group Manager and define Caller ID information in Dialplan Destinations.