Hunt Groups

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

Feature Functionality Benefit
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 finetune 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.

  • 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.
  • 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, seperated by space characters. If the list element contains a "np" (no pickup) flag after a colon seperator, 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.

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

/restGeneral REST API indicator
/huntGeneral indicator for the hunt group
/accountID of the hunt group, including the domain name (e.g. 77@localhost)
/dialGeneral 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.