====== Groups ====== RingRx Groups are used for routing communications to teams of users. .. contents:: :local: Group Features -------------- Call Routing ===================== Groups operate in one of three modes ``Basic Call Routing`` ====================== Calls placed to the extension of the group will: 1. If calls are recorded and :ref:`group_play_recording_announcement-label` is true a recording announcement will be played 2. If an entry media file is specified it will be played to callers 3. Members will be rung for :ref:`group_call_timeout-label` seconds Each users Call behavior will be evaluated and followed * :Ring My Phone: The users desk phone and mobile app will be tried * :Simultaneous Ring: The users desk phone and mobile app will be tried as well as their Mobile number at the same time * :Sequential: The users desk phone and mobile app will be tried THEN their mobile number * :Forward: The users mobile number will be tried 4. If an exit media file is specified it will be played to callers 5. If a forward destination has been set, it will be tried 6. The call will go to the groups mailbox ``Announcement Call Routing`` ============================= Announcement groups are used to create an ad-hoc PA system using the speakers of desk phones in the office. There are two kinds of announcement groups :Announcement: There will be a tone after each member device joins to indicate when to begin speaking :Announcement Mode B: Tones are suppressed for member device joins. Use this for groups with many member devices Calls placed to the extension of the group will: 1. If calls are recorded and :ref:`group_play_recording_announcement-label` is true a recording announcement will be played 2. If an entry media file is specified it will be played to callers 3. All members will be rung with the auto-answer flag set which will cause their phones to go off-hook on speaker. They will be muted so they will only receive audio from the caller like a PA system. 4. Any dialed party may press 2 on their phone to end the call and begin a 2-way conversation with the original caller .. note:: If your facility includes an integrated announcement speaker, that device may be included in an announcement group to simultaneously announce from both ``Queue Call Routing`` ====================== Queue groups are used to create a more flexible and intelligent method of call distribution as there would be in a call center. Full details are here: `Queues `__ ``SMS Routing`` ================ If a phone number has their incoming SMS messages routed to a group, any received messages will be sent simultaneously to all group members. In this arrangement the group effectively becomes the person the phone number is having a text message conversation with. When a message is received to a group: * A group message chat will start for all members of the group. * The off-network phone number will see replies as coming from the groups outbound SMS number .. note:: Take care to make sure that the outbound SMS number routes back to the group to avoid confusion When a group member responds to an inbound group message * All other members of the group will get that message sent to them * That message is sent to the outside phone number from the groups SMS number * The outside party has no visibility into which member of the group sent the reply keeping the appearance of a single presence. .. note:: Copies of all group messages will exist in each group members mailbox. IF a user is removed from a group, they will retain group messages from the time they were a member. Newly added members will only receive group messages going forward. ``Dynamic Member Login / Logout`` ================================= When :ref:`group_enable_login-label` is enabled, users can add or remove *themselves* from a group on demand from their phone, without an administrator editing the group's member list in the portal. This is commonly used to staff a ring group or queue by shift -- agents log in when they start and log out when they leave. Membership is changed by dialing a star code followed by the extension of the group: :Login: Dial ``*91`` immediately followed by the group extension. For a group at extension ``300`` the user dials ``*91300``. :Logout: Dial ``*92`` immediately followed by the group extension, e.g. ``*92300``. The user hears a confirmation tone and the call is released. .. note:: The group must have :ref:`group_enable_login-label` set to true, and the caller must be a user on the same account as the group. If login is not enabled for the group the star code has no effect. Behavior: * **Login is idempotent.** If the user is already a member of the group, logging in again does nothing -- it will not add a second copy of the user to the group. A user can safely dial the login code more than once. * **Newly logged-in members are added at the end of the group's order.** They are assigned the next ``priority`` value, so for queue groups using the *Static linear* distribution a dynamically added agent is tried after the members already configured on the group. * **Logout fully removes the user from the group.** Every instance of that user in the group is removed, so the user is cleared even if duplicate memberships had accumulated. Members added or removed this way behave exactly like members added or removed in the portal: a logged-in user appears in the group's member list (and receives group calls and messages) and a logged-out user disappears from it. Group Parameters ---------------- ``group type`` =============== :Default: basic :Description: The behavior of the group (Basic, Announcement, Queue) ``name`` ========= :Default: empty :Description: The name of the group. Mostly descriptive but it can be used ``extension`` ============= :Default: empty :Description: The dialable extension of the group .. _group_enable_login-label: ``group enable login`` ====================== :Default: false :Description: Enables the dynamic login/logout of members of this group using \*91 / \*92 star codes .. _group_call_timeout-label: ``call timeout`` ================ :Default: 24 :Description: Number of seconds for call legs in the group to timeout ``sequential`` =============================== :Default: false :Description: Indicates that group users should be rung sequentially. This only is used for basic groups .. _group_cnam_prefix-label: ``cnam prefix`` =============================== :Default: empty :Description: A string of text to pre-pend to the callerID name to be passed to the users. Can be used to add information to the call. .. _group_distinctive_ring-label: ``distinctive ring`` =============================== :Default: empty :Description: **For Polycom phones only** Will cause calls passing through the group to ring with a special cadence .. _group_entry_media_file-label: ``entry media file`` =============================== :Default: empty :Description: A media file from the accounts media library that will be played to callers **before** users are tried. A key press by the caller will terminate the media file and skip to ringing the users. .. _group_exit_media_file-label: ``exit media file`` =============================== :Default: empty :Description: A media file from the accounts media library that will be played to callers **after** all users have been tried without the call being answered. A key press by the caller will terminate the media file and skip to ringing the users. If a forward destination is specified or a mailbox, this file will be played before engaging either of those features. .. _group_forward_destination-label: ``forward destination`` =============================== :Default: empty :Description: An extension or phone number that the call will be offered to **after** all users have been tried. This destination will be tried for :ref:`group_call_timeout-label` seconds .. _group_mailbox-label: ``mailbox`` =============================== :Default: empty :Description: The voicemail box associated with the group. Calls that are not answered will end up in this voicemail box. .. _group_record_calls-label: ``record calls`` ================ :Default: false :Description: Will record calls to this group. Recorded calls will be found attached to the CDRs .. _group_play_recording_announcement-label: ``play recording announcement`` =============================== :Default: false :Description: Incoming calls will have an announcement played (before the entry media file) to indicate that calls will be recorded. .. _group_tags: ``tags`` =============================== :Default: empty :Description: A list of tags that will be attached to all of the calls passing through this group .. _group_outbound_sms_number-label: ``outbound sms number`` =============================== :Default: empty :Description: The phone number presented as the sender when a group member replies to an inbound group SMS conversation. Incoming texts to this number should be routed back to the group so replies stay in the same conversation. See the **SMS Routing** section above for the full group texting behavior. .. _group_callback-label: ``callback`` =============================== :Default: empty :Description: An optional callback that fires a ``CallAlert`` event each time the group is dialed. The event carries the group members being rung, letting an external integration be notified whenever the team receives a call. Leave empty for no callback. Queue Group Parameters ---------------------- These parameters only apply to queue mode groups .. _group_q_max_callers: ``q_max_callers`` =============================== :Default: 30 :Description: The maximum number of callers that can be waiting in queue .. _group_q_max_callers_dest: ``q_max_callers_dest`` =============================== :Default: empty :Description: The destination extension new callers are sent to when the queue already has the maximum number of callers waiting .. _group_q_max_wait: ``q_max_wait`` =============================== :Default: 1800 :Description: The maximum number of seconds a caller will be permitted to sit in queue. Defaults to 30min .. _group_q_max_wait_dest: ``q_max_wait_dest`` =============================== :Default: empty :Description: The destination extension callers in queue will be sent to when their hold time exceeds the max wait .. _group_q_moh: ``q_moh`` =============================== :Default: empty :Description: Music on hold to be played while users are in queue .. _group_q_alarm_on_max_wait: ``q_alarm_on_max_wait`` =============================== :Default: false :Description: Send alarm to all moderators and the queue alarm destination when a call reaches the max wait time .. _group_q_alarm_on_max_callers: ``q_alarm_on_max_callers`` =============================== :Default: false :Description: Send alarm to all moderators and the queue alarm destination when a call is rejected because the queue is at max callers .. _group_q_alarm_email: ``q_alarm_email`` =============================== :Default: empty :Description: Comma separated list of additional emails to receive queue alarms (in addition to moderators) .. _group_q_agent_wrapup: ``q_agent_wrapup`` =============================== :Default: 0 :Description: How many seconds to allow an agent for post-call activities before making them eligable for another call from the queue .. _group_q_agent_holddown: ``q_agent_holddown`` =============================== :Default: 30 :Description: How many seconds to suppress offering an agent a call after they failed to answer one (minimum is 10) .. _group_q_agent_dist_alg: ``q_agent_dist_alg`` =============================== :Default: Round-Robin :Description: How calls should be assigned from the queue to users * Round-Robin: Each user is assigned calls in equal rotation * Longest Idle: The agent who has been idle the longest is assigned the next call * Static linear: Agents are tried in fixed priority order (lowest ``priority`` value first), so the same agent is preferred until they become unavailable .. _group_q_annc_pos: ``q_annc_pos`` =============================== :Default: false :Description: When true, callers waiting in the queue periodically hear their current position announced ("Your position in line is currently number *N*"). The announcement repeats every :ref:`group_q_annc_pos_interval` seconds. .. _group_q_annc_pos_interval: ``q_annc_pos_interval`` =============================== :Default: 60 :Description: How often, in seconds, to re-announce a waiting caller's queue position. Minimum is ``15``. Has no effect unless :ref:`group_q_annc_pos` is true. .. _group_q_annc_pos_mediafile: ``q_annc_pos_mediafile`` =============================== :Default: empty :Description: Optional media file from the account's media library that will be played *immediately before* the position number. Leave blank to use the built-in RingRx prompt ("Your position in line is currently number"). Has no effect unless :ref:`group_q_annc_pos` is true. .. _group_q_breakout_digits: ``q_breakout_digits`` =============================== :Default: empty :Description: One or more DTMF digits (``0``-``9``, ``*``, ``#``) the caller may press at any time while in queue to escape the queue and be routed to :ref:`group_q_breakout_dest`. Multi-digit sequences such as ``*0`` or ``00`` are recommended over a single digit to avoid accidental triggering. Must be configured together with :ref:`group_q_breakout_dest` -- setting only one half is rejected as invalid. .. _group_q_breakout_dest: ``q_breakout_dest`` =============================== :Default: empty :Description: The destination extension a caller is transferred to when they press the :ref:`group_q_breakout_digits` while waiting in queue. Available destinations are the same set offered for :ref:`group_q_max_callers_dest` and :ref:`group_q_max_wait_dest`. Must be configured together with :ref:`group_q_breakout_digits`.