Agent Groups
  • 13 Jul 2021
  • 25 Minutes to read
  • Contributors
  • Dark
  • PDF

Agent Groups

  • Dark
  • PDF

An agent group, also known as automatic call distribution (ACD), is a system that routes incoming calls to a specific group of agents. Before connecting to an agent, callers are placed inside a queue, allowing agents to deal with incoming calls without losing other callers to busy signals or unanswered phones. While waiting, callers hear music and pre-recorded announcements . Agent groups can be monitored using a number of monitoring methods .

A caller reaches an agent group in one of two ways: either by calling the agent group directly or by calling a company's auto attendant. When agent groups branch off the auto attendant, callers must press the number that corresponds with their choice. The caller has reached an auto attendant offering three different choices: Sales, Accounting, and Support. The caller hears these options in the form of pre-recorded messages. Each option will connect the caller to an agent group, and the caller will be placed inside a queue until an agent becomes available.


Agent groups are often found in offices that handle high-volume customer calls from callers who do not need to speak with a specific person but who require assistance from any of multiple persons, like sales representatives and airline reservations attendants. Agent groups have a wide range of features .

Creating an Agent Group


  • Go to your selected domain in the Vodia PBX web interface.
  • Go to agent groups by clicking on Agent Groups under Accounts as shown above.
  • On top, click the tab Create to create a new agent group.
  • In the Account Name field, enter an extension number and/or alias, i.e., a DID number. When entering an alias in addition to an extension number, use the following syntax: 667/9781234567.

Note: If you use a space instead of a slash (667 9781234567), you will create two separate accounts that will be unrelated to each other.

  • To create multiple accounts at the same time, use a space between the numbers: 667 668 669
  • PressCreate.
  • The agent group(s) will be created which you can see in the "agent group list" or in "all accounts list", where you can enter each agent group just by clicking it, in order to modify it if you want, as explained below.

Configuring an Agent Group

Once you've created an agent group account, use the following information to configure it.

  • Go to your selected domain in the Vodia PBX web interface.
  • Go to Agent Groups .
  • Click on any agent group from the list that you want to change.
  • Here you can configure the settings. You can also go back to the list of Agent Groups, if you want, by clicking on the List tab above.

Explanation and Use of Some of the Settings Under Some Tabs

The settings are under different tabs.




  • Account Number(s): This field takes extension number(s) and/or DID number(s). The number of DIDs that can be entered into this field is unlimited.
  • Display Name: This field allows you to create an alias so that you can quickly identify the Account among other Accounts.
  • Outbound number (ANI) : This field shows the outgoing ANI to the callee if an agent that is logged into this ACD when dials out.
  • ANI for SMS : With this new feature the agents can now show a different ANI when SMS is sent out to external numbers.

Agent Setup

  • Primary Agents: This setting controls who is logged in the ACD as agent. The setting can be changed through the web interface, but it can also be changed with star codes, e.g. when the agent logs in from the IP phone. In the case of escalation the list of the additional agents will be added to the list, so that those agents don't have to log in.
  • Extensions that can add themselves ( for all):* This setting controls which agents can dynamically join or leave the agent group. It can also be used to add non-agents to the agent group, which can be useful during especially busy periods when additional people are needed for the queue. If a star is used in this field, extensions that use *64will automatically be listed in this field, i.e., the list will grow and decrease as people log in and out. It is recommended that actual extensions be entered into this field.
  • Number of logged in agents required to allow log out: This setting specifies the number of agents that must remain in the agent group before agents are permitted to jump out. If this setting is too high, agents will be unable to log out of the agent group. For small agent groups, a value of 1 is recommended.
  • Agent recovery time(s): Use this setting to ensure that an agent has adequate time to recover from the previous call before taking another call. In busy call centers, 2 seconds might be an appropriate setting. However, agents who are required to record notes about the call will need a longer value. In these cases, 60 seconds might be more appropriate. The recovery time also allows an agent to log out of the agent group.
  • Duration for flagging a missed call: This setting determines how long a call must have been ringing before it is considered a missed call for an agent. If the agents picks up the call after this timeout this call is not considered a missed call.
  • Allow multiple ACD calls on agent - even if busy: This setting allows a caller to be sent directly to an agent, even if all agents are busy. It prevents the caller from sitting there listening to music and gives the agent the opportunity to put their current call on hold and take the new call. This setting should generally not be used.
  • Allow agents to divert incoming calls: If this setting is turned on, agents can use their VoIP phones to deflect incoming calls to another destination. Please not that some phones will send call redirections by themselves, for example because a local call redirect after timeout or a call redirect for all calls was set on the device.
  • Allow multiple calls to ring agents in parallel: When this flag is set, the ACD will proceed ringing more agents even if there are more calls ringing up agents. This generally makes sense when there are only one or only few agents added in each stage or there are a lot of agents available for accepting calls.

Agent Selection

  • Algorithm for Selecting next agent: The agent selection algorithm allows you to establish the method that will be used by the system when connecting a caller to an agent. Choose from the following options:

    • Random: This algorithm randomly selects the next agent. This is a reasonable algorithm in environments where it is not important as to which agent processes the call.
    • Ring longest idle first: This algorithm is designed to balance active call time amongst all the agents. The queue keeps a list of the agents and moves an agent to the end of the list when an agent connects a call. This ensures that the agent with the longest idle is at the front of the list.
    • Use preference from the Agent's setting: This algorithm uses the extensions listed in the Agent setting. The agent listed first will be tried first. If that agent is busy, then the system will jump to the second one and so on.
  • All agents for this ACD: If the algorithm for the ACD was set to "Use preference from the Agent's setting" then the system will add the additional agents from below ("After hearing ringback for (X) seconds", escalation) and use the resulting list as the preference to find the next agent from the front of the list to the back.

  • Position for adding agent: Depending on your setting, newly logged in agents will be positioned at the front of the queue or the back.

  • Ring stage duration (secs): At regular intervals, the system checks agent availability and determines whether the next caller should be pulled out of the waiting state. The ring stage duration setting establishes this interval. For larger queues, shorter intervals are recommended, as it is quicker to get callers out of the queue and into a ringback state. The default value for this setting is 5 seconds.

  • Number of agents added per stage: In every scheduling interval, the system adds only a limited number of agents from its pool of available agents to its list of ringing agents. For large agent groups, a typical value would be one or two, as this will ensure that not all agents receive calls at the same time and so that the system CPU is not overtaxed with simultaneous calls.

Redirecting Calls From Queue

This section allows you to establish timeout settings that will determine the length of time a call is kept in queue or ringback state in a given situation. In this section, you can instruct the system to add additional agents or to redirect a call after the call has been in ringback for a given length of time. You can also instruct the system to redirect a call once a caller's wait time has passed a certain threshold.

  • After hearing ringback for ... seconds, include the following additional agents. Use this setting when additional people in the office can help out when no one else is picking up. Result: When calls are not picked up within the specified period, the system adds these extensions to the list of potential candidates that might be included (depending on the algorithm).
  • After hearing ringback for ... seconds, the system will redirect the call to the destination. The destination can be either an internal number (e.g., a hunt group) or an external number (e.g., a cell phone or home number). This option is similar to the previous option but instead of ringing both the original and new agents, the system cancels the original agents and redirects calls to the new agent(s) or to the external number. If you redirect the call to the same ACD, the call will be put back at the front of the queue and be scheduled as the next call to ring agents.
  • Automatically log agents out after redirecting a ringing call: This setting will log agents if the call in the ACD was redirected while agents were ringing. Agents need only log back in to return to the agent group. This setting is directly linked to the After hearing ringback settings. The caller is redirected to the extension or agent (whichever is chosen) that has been specified in that setting after the timeout in that setting has been reached.
  • If the caller has already waited longer than (X) seconds,the system will redirect the call to the destination. If a caller has waited a while in the queue, this will immediately redirect the call to another destination. Note: The caller is classified as "waiting" when all agents are busy with other customers and the new caller is waiting for a free agent.
  • Redirect destination for suspected SPAM calls - If the ACD inbound call has been suspected as a SPAM call by the PBX (from the domain / admin level SPAM detection settings) then number entered here will be where these calls will be redirected.


  • Ring Melody for agents: It is important to set the ring melody so that the phone knows which one to play and so that agents will be able to distinguish regular calls from agent group calls.

    • Custom 1 through 4: Custom ringtones allow users in an agent group to distinguish agent group calls from other calls. Before customized ringtones can be used, you will need to provide your own ringtones, modify the ringtones.xml file, then place it into the html directory. When the phone receives the alert-info header from the system, it will respond with a different ring tone based on the ringtone that was selected from the web interface.
    • External Call: The ring tone will be long.
    • Internal Call: This ring tone will be short.
  • Event for connecting the call: This setting allows you to tell the system when to pick up the line if the line has not been picked up already (for example, by an auto attendant).

    • Entering the agent group: The call is picked up when it enters the agent group. In most cases, this is suitable behavior.
    • Music playback: If the caller has to wait for an available agent, the caller is put on hold and hears music while waiting. If the call goes directly to an agent, the queue waits until the agent picks up the call before connecting it.
    • Agent picks up call: The call is not connected until the agent picks up the call, even if music on hold and/or announcements have been set. This option is useful if the waiting time in the queue is typically very short and there's no risk of the carrier disconnecting the call due to no answer.
    • Never connect: The call is never connected. This is useful if you want to provide free services to callers. This setting prevents the carrier from seeing the call. As with the other options, there is a risk that the carrier will not tolerate this behavior and will hang up the call after a certain timeout.
  • Priority: This setting determines which agent group will be the priority when an agent is part of multiple agent groups. For example, if two calls are on two agent groups and the PBX has to choose this agent, it uses this setting to determine which agent group call has the higher priority.

  • Maximum number of calls: If you want to limit the number of active calls on the agent group, you can use this setting.

  • After the maximum calls is reached: This setting determines what the system should do when the maximum calls have been reached. The system can either reject the call or instead connect the call and play a message.

  • From - Header: This setting allows agents to see who the call is coming from. By default, the name of the calling party is displayed, but the system can be configured to display the name of the queue (see From Header in Groups ), either by itself or with the calling party. When both are shown, the system puts the caller-ID in brackets after the display name. This mode requires that the phone have enough space to display a long number. When using this mode, choose a short group name so that it requires less space.

  • Automatically add CMC: When this feature is turned on, the caller's CMC will appear in every CDR that is written on the disk. The CMC is used for automatic billing.

  • Call routing based on: This feature allows callers to be connected to agents who have handled their calls in the past.

    • Queue entry time: All callers will be placed in queue and will remain there until an agent becomes available.
    • Try to pull out callers when their last agent becomes available: Callers will be pulled from the queue if their last agent becomes available.
  • Dial plan for outbound calls: Select the dial plan that will be used for this account. For more information on dial plans.

  • Page incoming calls: Click on Addand select the Paging group account that should announce the caller's information everytime there is an incoming call. Then, navigate to the Paging account and turn on the settings under Call Announcementsection as per need. Note : If it's a PBX hosted on a public server then select a Unicast Paging account (Multicast Paging won't work on a Public server). For LAN paging, both Unicast and Multicast paging can be selected to accomplish this.

  • Turn off the cell phone forking: By default the ACD will try to include the agent cell phone when trying to connect a call. This behavior can be turned on on the users profile, but it can be disabled per ACD as well.

  • ANI: The agent group uses an ANI (automatic number identification) when sending a caller to an external number. This setting is necessary when the user input handling destinations take callers to external numbers rather than extension numbers within the domain. For more information, see Trunk ANI . When an extension logs into a ACD, it will use the ACD ANI for outbound calls (if it was set) and replace the ANI of the extension (see ANI setting for extensions ). This behavior can be changed on the trunk level by changing the rules for the ANI determination.

Night Service

Night service is used to redirect calls to other extensions or phone numbers during certain times of the day/night or other events that are outside normal business hours. Before night service can be used, a service flag account must be created for each night service number.

The first three settings in Night Service allow you to make provision for when no agents are available:

  • When primary agents are logged out, send calls to: "Primary agents" refers to the agents that are entered into the All agents for this ACD field.
  • When all agents are logged out, send calls to: "All agents" refers to the agents that are entered into the All agents for this ACD field, as well as the extensions that are entered into the Caller in Queue fields.
  • When all agents are unregistered, send calls to: It is best to enter a number that is not part of the PBX (e.g., an external number) since the extensions may also be unregistered if the registration issue is due to a power outage.

The following two settings are used to configure the service flag(s) to night service numbers:

  • Service Flag Account: Once you have created the service flag account(s), enter the number of the account(s) into this field.

Note : You may specify more than one night service flag (separated by a space). The first service flag account will correspond to the first night service number, and the second service flag account will correspond to the second night service number, etc.

  • Night Service Number: Once a service flag is in place, calls will be directed to the night service number(s) indicated here. Internal extensions or external number phone numbers are permitted in this field.

Note : You can also use a special character pattern (#L) to activate the service flag when all agents are logged out, even if the logout period is within normal working hours. All calls will automatically be redirected to the specified night service number(s).

Caller Setup



  • Ringback tone:

    • Regular ringback tone when agent rings: The caller will hear the agent ringing.
    • No ringback tone, continue playing music: Instead of hearing a ringback tone, the caller will hear music. If an agent is no longer at his desk but has not logged out of the agent group, the caller will hear music on hold instead of ringback.
  • Music on Hold source: From the dropdown list, choose the music that the caller will hear while waiting for an agent.

  • Background Music: This setting enables you to continue playing the music on hold while playing the messages.

  • Accounts that may record a message: Specify which accounts may record announcements. When this setting is left empty, all extensions will have permission to record announcements.

  • Gap between announcement(s): From the dropdown list, select the number of seconds that the system should wait between each announcement.

  • Queue position announcement: When Announce queue position is selected, an announcement will let callers know their position in queue.

Upload Messages

The number of available greetings within any agent group is nine. Record only those greetings that should be used. If no greetings are needed, even an initial greeting, don't record any. When recording greetings, you need to assign a number to each greeting; for example, *0is the entry greeting, *1is the first greeting, *2is the second greeting, etc. The number is entered as the last number in the string.


Instead of having callers wait in the ACD, the system can instead call waiting callers back when it is their turn.

In order to enable this, the ACD needs to offer a call back key which will be annouced to the caller. The ACD will annouce the callback possibility when entering the queue either always, never or depending on the expected waiting duration of the caller. Typically only callers that are facing a significant waiting time will use the callback feature.

On order to avoid fraud a dial plan is needed for the callback. The number needs to match with a trunk in the dial plan. This makes it possible to use an existing dial plan or set up a dedicated dial plan for the ACD.

When the user presses the selected key, the system will play an IVR that asks the caller to confirm the caller-ID or enter a different caller-ID. For numbers that are not on the dial plan, the system will immediately ask for a different caller-ID until it matches the dial plan. This ensures that only numbers which are on the dial plan will enter the callback list.

When the system calls the number, the system will play back an annoucement to the user about the callback and then puts the caller into the ACD at the position where the caller would be when juts holding the call. The number of attempts and the waiting duration between the attempts is set with the general outbound calling parameters below.


Post-Call Survey

After the call is over, the system can collect a feedback from the caller. In that case, the agent needs to disconnect the call and the caller needs to stay in the call. There are two ways to receive a feedback. The first one is to redirect the call to an external survey number, for example survey services outside of the system.
The second possibiity is to use the built-in feedback mechanism that asks for a 1 to 5-star rating of the call. The rating will be logged along with the CDR for the call and is available throughout the various reporting mechanisms for the ACD.
If the caller leaves a low rating this may trigger a follow-up with the caller. For this the system offers a redirection number, which is typically a manager that will check what went wrong.

Screen Shot 2021-07-13 at 11.34.41 AM.png

Caller Options

Caller options allow the caller to exit the agent group queue and connect to another destination. To give the caller this option, use the Caller Options fields to map telephone keypad numbers to other extensions or phone numbers.

Once extensions or phone numbers have been entered into the "Key" fields, the caller must be made aware that these options are available. The system will not do this automatically. The place to do this is through the greetings that are delivered by the system (using the *98star code feature). One greeting or several greetings can be used to inform the caller that this additional option is available. In the following table, greeting 2 informs that caller that key 1 can be pressed to leave a message.

Greeting Message Caller Option
0 Welcome to CompanyABC. Your call is important to us. Please hold.
1 Sorry our lines are still busy . . . Have you looked at the support site for answer to your question?
2 Our newest release offers this and that . . . If you want to leave a message, please press 1 now. 503
3 Another message . . .
4 Another message . . .

The Message-Music Cycle

While the caller is waiting, the system delivers a combination of pre-recorded messages and music. The messages can be used to provide additional information about your company, or they can be used to provide the caller with additional options and/or a way to exit the queue. Each agent group can be configured to play up to nine recorded messages. Between the messages are "gaps" of music which can be configured to span 5 to 180 seconds. This messagemusic cycle continues for as long as the caller is in the queue. Message 0 is considered the entry point message (which will never be replayed), and message 1 is the first message. an agent group using six different messages for its message-music cycle. Once message 6 has been played, the system returns to message 1 and repeats the cycle.

This sequencing of messages and music will continue until an agent becomes available. Once an agent is available, the system automatically takes the next call out of the queue, rings the agents, and puts the call into ringback state. Within any one agent group, only one call at a time can be in ringback state, regardless of the number of agents that are available. All other calls remain queued until the ringing call is connected and at least one agent becomes available.

While it might seem logical to conclude that a caller's time in the queue has ended once the call has been placed in ringback state, this is not always the case. If an agent leaves the desk without logging out of the queue, the ringback state will continue until the system finds another agent to answer the call. To prevent nonstop ringing, you can take two precautions: (1) you can configure the agent group to include additional agents at specified intervals in the ringback cycle and (2) you can configure the agent group to play music during the ringback state. This will prevent the caller from hearing long periods of ringing in the event there are episodes of extended ringback.
Record Greetings

  1. Dial *98followed by the number of the agent group, then the greeting number (e.g., *1).
  2. Press theconfirm button on the telephone keypad.

Listening to Greetings from the Phone
To listen to greetings quickly from the phone, change the gap between announcements to 1 and call the agent group directly from your phone. The recorded messages will be played quickly.

Outbound Calling

The agent group's Outbound Calling page allows the agent group admin to set up outbound numbers for agent dialing. Once the outbound numbers have been configured for the agent group, users can initiate calling using the ACD outbound calling star code or have the system start the calling (see below).

The following settings control how the outbound calling works. Some settings also affect the automatic callback feature (see above).

  • Call outbound numbers up and then queue When this flag is set to on, the PBX will call the numbers up without the agents having to dial the star code. Otherwise the agents need to trigger the call.
  • Required number of available agents In order to make sure that the call will get to an agent, there needs to be a certain number of agents available. This settings controls that.
  • Maximum number of retries If the call fails, the PBX will reschedule the number for later and try again. When the number of retries has reached the maximum number the number will be marked as failed.
  • Maximum number of waiting callers As with the number of available agents, the number of waiting callers will slow down the calling until the ACD has capacity to take an additional call.
  • Timeout for connecting calls This setting controls how long the PBX will keep the call ringing until giving up and considering this call attempt failed.
  • Key for connecting the call In many cases it is useful to ask the called number to confirm the call in order to rule out that the call has not reached a mailbox. This setting controls what key to ask for or wheather to ask for a key at all.
  • Duration between call attempts for a number If a call fails, the system will wait a certain time before trying to call again.

Screen Shot 2021-07-13 at 11.17.42 AM.png

Adding outbound numbers

  1. From the agent group's Outbound Calling page, enter a phone number into the Add a number for outbound call field.
  2. Click Add. The number shows up under the table below. This number will be available for agent calling.
  3. Repeat these steps for additional numbers.

You can also import numbers through the CSV import dialog.

Initiating ACD Outbound Calls

To initiate dialing, agent group members can dial *55xx(where xxis the number of the agent group).

The Vodia PBX plays a few prompts to help the agent navigate during the calling process.

Managing the Outbound Call List

After a successful call, the Status changes to Ok for the dialed number. This means that the number will not be attempted again. If you want the Vodia PBX to attempt that number again, you have to reset the Status for that number. This can be done by selecting the check box and clicking theReset button. If you do not want to keep the number in the outbound call list, you can select the number and click Delete . This removes the number from the list.

Agent Log in/Log out

Agents must log into the queue to begin receiving calls. When agents have finished for the day or would like to stop receiving calls from the queue, they must log out of the queue.

Agent group members can use one of two methods (buttons or star codes) when logging in and out of agent groups.

Important: Before agents can use either method, agents must be included in the Extensions that may jump in or out setting. Another setting that must be considered is theMinimum number of agents for jumping out setting (shown below). The latter setting is used to prevent the agent group from becoming too small; however, if this setting is too high, agents will be unable to log out of the agent group.

Method 1: Buttons

This method allows users to use a button on their phone to log in and out of agent groups. When configured properly, the button will have a toggle effect. When the button is pressed, users will be logged in to all agent groups, and the associated LED(s) on their phone will light. When the button is pressed again, users will be logged out of all agent groups and the associated LED(s) will no longer be lit. If users need to log out of one agent group before logging into another, multiple Agent login/logout buttons can be configured.

Important: Before you can use this button, the star codes for Agent logged in/Agent logged out must match (e.g., *65/ *65).

Method 2: Star Codes

When using star codes to log in and out of agent groups, users have the flexibility of logging in and out of all agent groups to which they belong or just a specific group. The standard Agent logged in/Agent logged out (*64/*65) star codes (without any argument) will log the agent in to or out of all agent groups:

Agents who are members of numerous agent groups and who need to log out of one agent group before logging into another can do so by entering the agent group number after the star code. Using the sample shown below, the agent will be logged out of agent group 666 and will retain logged-in status for all other agent groups.

Queue status URL

See here for more information.

Was this article helpful?

What's Next