Hunt Groups
  • 05 Feb 2021
  • 13 Minutes to read
  • Contributors
  • Dark
  • PDF

Hunt Groups

  • Dark
  • PDF

A hunt group is a set of extension numbers that are embedded inside a single virtual extension. Incoming calls are rotated through the pool of extensions until someone answers and the caller is connected. (Cell phones can also be configured to be included in calls made to a hunt group.)

Creating a Hunt Group



  • Go to your selected domain in the Vodia PBX web interface.
  • A pop up window would give you a chance to enter the details in the new GUI.
  • Go to hunt groups by clicking on Hunt Groups under Accounts as shown above.
  • On top, click the tab Create to create a new hunt 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 hunt group(s) will be created which you can see in the “hunt group list” or in “all accounts list”, where you can enter each hunt group just by clicking it, in order to modify it if you want, as explained below.

Configuring a Hunt Group

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

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

Explanation and Use of Some of the Settings



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.

Name: This field allows you to create an alias so that you can quickly identify the Account among other Accounts.

Outbound number (ANI): The hunt group uses an ANI (automatic number identification) when sending a caller to an external number. For more information, see Trunk ANI .


The extension numbers that are part of a hunt group can be arranged into groups known as stages. Each stage is configured to ring for a specified period before the system begins ringing the next stage. To continue ringing the same extension throughout all stages, include that extension in each ring stage. A last-resort or final stage number (often an auto attendant or a cell phone) can also be used when none of the extensions pick up the call. A common use case for the hunt group is to use the hunt group as the main number for incoming calls, then put the receptionist, secretaries, and assistants on the different stages.

You can also include regular numbers in the hunt groups, not only extensions. That makes it possible to call devices that cannot register as SIP endpoints. If you want to include cell phones in hunt groups, you better use the extensions number and enable the cell phone forking in the extension setting.

The hunt group supports three stages and a final stage. Each stage can be configured to ring for a different number of seconds, and the final stage can be either an internal or external phone number.

For each stage:

  1. List the extensions or numbers that should be part of that stage. When entering multiple extensions, use a space as a separator (only one number is permitted for the final stage).
  2. For duration, specify the length of time that the system should ring each stage before ringing the next. The duration of the stages must be specified in seconds.
  3. For unwanted stages, leave the fields empty.

If all extensions of a stage are unavailable, the system will immediately move to the next stage.

If you check the missed flag for the stage, the PBX will send a missed call indication to the phone when it moves to the next stage and the phone is not part of the next stage.

Note : The number of extensions permitted for the first three stages is limited by hardware only. The system must send INVITEs to all extensions in each stage, which requires more CPU.

Hunt Group Features

Custom ringing Each hunt group can be configured with different ring tones.Employees can determine which hunt group is calling.

BLF indicator The system can be configured so that the busy lamp field indicator lights up when the hunt group is in use.Hunt group activity is visible through the BLF indicator.

Group name caller-ID Hunt groups can have a unique name and can be configured to display the name of the group, the caller’s caller-ID, or both when a caller enters a hunt group.Helps management decide who belongs in each named group. Employees know the nature of the call before answering it.

Three-stage extension ringing Hunt groups can be configured to ring 1–3 different groups of extensions. The system will ring each group in succession until the call is answered.Managers can direct calls to selected groups of extensions in a specified order.

Final stage to cell phone After calling the extensions listed in stages 1 through 3, the system calls the “final stage” number, which can be an auto attendant, an extension, or an external number.Callers are sent to a manager as a final means of assistance. This feature can also be used to gauge whether the group of extensions is too small or whether the employees are working properly.

Ring stage duration Hunt group stages can be configured to ring for different durations before the system rings the next group of extensions.Call flow control can be established. Intervals that keep customers waiting a minimum amount of time can be used.

Recordable calls Calls made to hunt groups can be recorded and saved on the system.Recorded calls can be reviewed by management to fine-tune employee performance. Disputes can be easily resolved by emailing the recorded conversation.


Behavior settings allow you to control numerous account behaviors. You can choose a ring melody, a display header, and music on hold source. You can also enter a safety net phone number that will be used if no one picks up a call. Other settings are here as well.

  • Algorithm: By default, the hunt group calls all agents, IVR nodes and numbers in each stage up and connects the call to the first that accepts the call. In the case of IVR nodes this is the first that is idle. If the algorithm "Select most idle agent per stage" the system will call only one agent per stage. This makes it possible to automatically balance the call load on several extensions in a fair way.

  • Ring Melody: This setting allows you to set the ring melody so that hunt group members will be able to distinguish regular calls from hunt group calls.

    • Custom 1 through 4: Custom ringtones allow users in a hunt group to distinguish hunt 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 phones 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.
  • From Header: This setting allows you to set the display name that hunt group members will see when someone is calling. More information on this subject is available on a separate page From Header in Groups .

  • Dial plan for outbound calls : This setting allows you to configure dial plan behavior that is different from what has been set on the extension. For example, if the dial plan on the extension does not allow for outbound calling, but you want to allow the extension to receive hunt group calls on their cell phones (see When calling the extension in a hunt group ), you can select a dial plan here that would allow for that. There are many other uses for this setting as well.

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

  • Send daily CDR report to : The call data record (CDR) lists all calls that come into the hunt group. The report is sent at midnight each night to the email address listed in this field (e.g., Only one email address is allowed in this field.

  • Permissions to monitor this account: This setting defines which extensions may monitor the status of this account, for example with a BLF button. By default, all extensions are allowed to see the status of an account. The setting is a list of extensions and wildcard patterns, separated by space characters. If the list element contains a "np" (no pickup) flag after a colon separator, then the monitoring will show only if the account is idle or busy. An example for this settings would be "41 42 5* 61:np 70*:np". The "np" flag was introduced in version 61.

  • Music on hold source : From the dropdown list, choose the music that callers will hear while waiting.

  • Record incoming calls to hunt groups : When this setting is enabled, the system will record all calls that come into the hunt group. The recordings can later be retrieved and reviewed.

  • Turn off the cell phone forking: The cell phone inclusion of the agents cell phones can be turned off specifically for this hunt group.

  • Allow agent connect ActionURL: When this flag is set the PBX will trigger the ActionURL for connecting an agent.

  • Enable call pickup from extension BLF: By default, the PBX will show that an extension is busy when a call rings the agents phones. If this flag is turned it, the PBX will make it possible to pick the hunt group up from the extension BLF.

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

  • CRM account: When using CRM integration, the system needs to associate a call to the hunt group with an account that exists on the CRM system if there was no agent that picked up the call (e.g. in the case of a missed call).

  • Redirect destination for suspected SPAM calls: If there is a suspected SPAM call, this field tells the system where to redirect the call. If the field is empty the system will accept the call.

Night Service

Night service allows you to redirect calls to other extensions during off-hours, meetings, etc. Before you can use night service, you need to create a Service Flag account.

  • Service Flag Account : Once you have created the account, enter the number of the account.
  • Always: This rule will always redirect calls. This can make sense if this is the last rule in a list of other rules.
  • No agent has phone registered: This rule is useful when an office has lost internet connectivity and all agents went offline and the agents are not using any cell phone inclusion. A redirection target can be for example another hunt group, a mailbox or another hunt group that has the cell phone inclusion turned on.
  • Night Service Number : With a service flag in place, the hunt group can redirect the calls directly to the night service number(s) shown in this field. Internal extensions and external numbers are acceptable.

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.

From Header in Groups

In Hunt Groups and Agent Groups, the PBX is able to display more information about where the call comes from.

Generally speaking, the remote party information consists of two components, the "display name" and the URI. For example, if the display name is "Group 1" and the URI is, the remote party information would be "Group 1" . What is being displayed, depends on the settings of the phone that you are using. Many phones are only displaying the display name; others only display the user part URI between the "sip:" and the "@" symbol.

The web interface offers the following modes:

  • Calling-Party: In this mode, it just displays the calling party like on a regular incoming call. This is the default setting for the display. An example would be "Joe Doe".
  • Group name: If you select this mode, the PBX will put the name of the group into the display of the phone; the URI remains unchanged. An example would be "Group 1" .
  • Group name (Calling Party): In this mode, the PBX will use the name of the group in the front with display name of the calling party in brackets behind it. For example, if the calling party is "Joe Doe" and the group name is "Group 1", the PBX would send "Group 1 (Joe Doe)" to the phone.
  • Group name (Calling Number): This is similar to the previous mode, but the PBX puts the username into the brackets. For example, if the calling party is "Joe Doe" and the group name is "Group 1", the PBX would send "Group 1 (2121234567)" to the phone.
  • Calling-Party (CMC): In this mode, the PBX puts the client matter code (CMC) into brackets in the display name, if present in the address book. For example, if the calling party is "Joe Doe" and the CMC for the number 2121234567 is 54256, the PBX would send "Joe Doe (54256)" to the phone.

In addition to that, you may also add other information manually into the setting. You can that by editing the template for the hunt group or agent group web page (add a option to the select for from_header). Here, you may use the following pre-set variables when generating the display name:

  • "f" is being replaced with the calling party username.
  • "t" is being replaced with the called party username.
  • "g" is being replaced with the display name of the calling party.
  • "c" is being replaced with the CMC code (if present).

For example, if the calling party username is "123" and the called party "456" and you select the Customized, then the SIP URI would look like "123 to 456" in the above examples.


You can initiate hunt group calls from the REST API. This has the effect that the PBX will first try to connect to one of the listed destinations before calling the other side of the hunt group. This can be useful for example when including multiple parties in click to dial functions or when a message has to be played to one person in a group of people, for example for an alarm system.

The REST call has the following components:

Element Function

/rest General REST API indicator

/hunt General indicator for the hunt group

/accountID of the hunt group, including the domain name (e.g. 77@localhost)

/dial General indicator for the dial function.

/destinationDestination to call after one of the hunt group destination picks up.

All URL components must be properly URL-encoded. The request must have at least domain authentication, either by a session or by Basic authentication header.

Was this article helpful?

What's Next