Hunt Group

Defining hunt groups allows you to redirect overflow calls to a destination when the group cannot accept calls.

General

Create instance

POST /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/services/hunt_groups/

Create a new hunt group in a group.

Example request:

POST /api/v1/tenants/foo/groups/foogroup/services/hunt_groups/ HTTP/1.1
Host: example.com

{
   "serviceUserId": "APIOTestHuntGroup,
   "serviceInstanceProfile": {
       "name": "APIO Test Hunt Group",
       "cliLastName": "Last Test",
       "cliFirstName": "First Test",
       "department": {
           "tenantId": "ApioSpTest",
           "groupId": "ApioGrpTest",
           "departmentName": "test_department_initial"
       },
       "language": "English",
       "timeZone": "Europe/Brussels",
       "timeZoneDisplayName": "(GMT+01:00) Europe/Brussels"
   },
   "policy": "Regular",
   "agents": ["ApioUserTest@sip.netaxis.be"],
   "active": true,
   "templateName": "basic"
}
Request JSON Object:

Example response:

Response:

Similar to GET instance method response.

Status Codes:

Retrieve instance

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/services/hunt_groups/(string: hunt_group_name)/

Retrieve a hunt group.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/services/hunt_groups/APIOTestHuntGroup@sip.netaxis.be/ HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK

{
   "serviceUserId": "APIOTestHuntGroup,
   "serviceInstanceProfile": {
       "name": "APIO Test Hunt Group",
       "cliLastName": "Last Test",
       "cliFirstName": "First Test",
       "language": "English",
       "phoneNumber": "",
       "extension": "",
       "department": {
           "tenantId": "ApioSpTest",
           "groupId": "ApioGrpTest",
           "departmentName": "test_department_initial"
       },
       "publicUserIdentity": "",
       "timeZone": "Europe/Brussels"
   },
   "policy": "Regular",
   "huntAfterNoAnswer": false,
   "allowMembersToControlGroupBusy": false,
   "notReachableForwardToPhoneNumber": "",
   "enableNotReachableForwarding": false,
   "makeBusyWhenNotReachable": false,
   "agents": [
      {
          "userId": "ApioUserTest@sip.netaxis.be",
          "lastName": "Test",
          "firstName": "Test",
          "weight": 60,
          "phoneNumber": "",
          "extension": "4000",
          "department": {
              "tenantId": "ApioSpTest",
              "groupId": "ApioGrpTest",
              "departmentName": "test_department_initial",
              "fullPathName": "test_department_parent_1 \\ test_department_initial"
          },
          "emailAddress": "test_mail@test.netaxis.be"
      },
      {
          "userId": "ApioUserTest1@sip.netaxis.be",
          "lastName": "Test1",
          "firstName": "Test1",
          "weight": 40,
          "phoneNumber": "+3225126778",
          "extension": "5001",
          "emailAddress": ""
      }
   ],
   "useSystemHuntGroupCLIDSetting": true,
   "noAnswerNumberOfRings": 5,
   "enableGroupBusy": false,
   "forwardToPhoneNumber": "",
   "forwardTimeoutSeconds": 0,
   "forwardAfterTimeout": false,
   "allowCallWaitingForAgents": false,
   "applyGroupBusyWhenTerminatingToAgent": false,
   "includeHuntGroupNameInCLID": true,
   "active": true
}
Response JSON Object:
Status Codes:

Retrieve list instances

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/services/hunt_groups/

Retrieve the list of hunt groups.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/services/hunt_groups/ HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK

{
   "hunt_groups": [
      {
         "serviceUserId": "APIOTestHuntGroup@sip.netaxis.be",
         "name": "APIO Test Hunt Group",
         "phoneNumber": "",
         "extension": "",
         "department": {
             "tenantId": "ApioSpTest",
             "groupId": "ApioGrpTest",
             "departmentName": "test_department_initial",
             "fullPathName": "test_department_parent_1 \\ test_department_initial"
         },
         "active": true,
         "policy": "Regular
      }
   ]
}
Response JSON Object:
Status Codes:

Update instance

PUT /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/services/hunt_groups/(string: hunt_group_name)/

Update a hunt group.

Example request:

PUT /api/v1/tenants/foo/groups/foogroup/services/hunt_groups/APIOTestHuntGroup@sip.netaxis.be/ HTTP/1.1
Host: example.com

{
   "serviceInstanceProfile": {
       "language": "French"
   },
   "queueLength": 10,
   "agents": ["ApioUserTest@sip.netaxis.be", "ApioUserTest2@sip.netaxis.be"],
}
Request JSON Object:

Example response:

Response:

Similar to GET instance method response.

Status Codes:

Delete instance

DELETE /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/services/hunt_groups/(string: hunt_group_name)/

Delete a hunt group.

Example request:

DELETE /api/v1/tenants/foo/groups/foogroup/services/hunt_groups/APIOTestHuntGroup@sip.netaxis.be/ HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Status Codes:

Available Agent List

Retrieve list of possible agents

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/services/hunt_groups/users/available/

Retrieve a list of users that can be assigned to a given Hunt Group. Searching for users by group only makes sense when the hunt group is part of an Enterprise. It is possible to filter the list to the same Group only by using the specific parameter sameGroupOnly.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/services/hunt_groups/users/available/ HTTP/1.1
Host: example.com
Request JSON Object:

  • sensitiveDepartmentEquals (object) – See sensitiveDepartmentEquals from Search criteria.

  • sensitiveUserGroupEquals (object) – See sensitiveUserGroupEquals from Search criteria.

  • sameGroupOnly (boolean) – to filter the list to the same Group only.

Example response:

HTTP/1.1 200 OK

{
   "available_users": [
      {
          "userId": "ApioUserTest@sip.netaxis.be",
          "lastName": "Test",
          "firstName": "Test",
          "phoneNumber": "",
          "extension": "4000",
          "department": {
              "tenantId": "ApioSpTest",
              "groupId": "ApioGrpTest",
              "departmentName": "test_department_initial",
              "fullPathName": "test_department_parent_1 \\ test_department_initial"
          },
          "emailAddress": "test_mail@test.netaxis.be"
      },
      {
          "userId": "foouser@sip.netaxis.be",
          "lastName": "Test",
          "firstName": "Test",
          "phoneNumber": "",
          "extension": "4004",
          "emailAddress": "test_foomail@test.netaxis.be"
      }
   ]
}
Response JSON Object:

Example request with sameGroupOnly:

GET /api/v1/tenants/foo/groups/foogroup/services/hunt_groups/users/available/ HTTP/1.1
Host: example.com

{
   "sameGroupOnly": true
}

Example response:

HTTP/1.1 200 OK

{
   "available_users": [
      {
          "userId": "foouser@sip.netaxis.be",
          "lastName": "Test",
          "firstName": "Test",
          "phoneNumber": "",
          "extension": "4004",
          "emailAddress": "test_foomail@test.netaxis.be"
      }
   ]
}
Status Codes:

Retrieve weighted distribution of an instance

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/services/hunt_groups/(string: hunt_group_name)/weighted_distribution/

Retrieve the weighted distribution of a hunt group.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/services/hunt_groups/APIOTestHuntGroup@sip.netaxis.be/weighted_distribution/ HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK

{
  "agents": [
      {
          "userId": "ApioUserTest@sip.netaxis.be",
          "lastName": "Test",
          "firstName": "Test",
          "weight": 60,
          "phoneNumber": "",
          "extension": "4000",
          "department": {
              "tenantId": "ApioSpTest",
              "groupId": "ApioGrpTest",
              "departmentName": "test_department_initial",
              "fullPathName": "test_department_parent_1 \\ test_department_initial"
          },
          "emailAddress": "test_mail@test.netaxis.be"
      },
      {
          "userId": "ApioUserTest1@sip.netaxis.be",
          "lastName": "Test1",
          "firstName": "Test1",
          "weight": 40,
          "phoneNumber": "+3225126778",
          "extension": "5001",
          "emailAddress": ""
      }
  ]
}
Response JSON Object:
Status Codes:

Update weighted distribution of an instance

PUT /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/services/hunt_groups/(string: hunt_group_name)/weighted_distribution/

Update weighted distribution of an instance.

Example request:

PUT /api/v1/tenants/foo/groups/foogroup/services/hunt_groups/APIOTestHuntGroup@sip.netaxis.be/weighted_distribution/ HTTP/1.1
Host: example.com

{
  "agents": [
      {
      "userId": "ApioUserTest@sip.netaxis.be",
      "weight": 40
      },
      {
      "userId": "ApioUserTest1@sip.netaxis.be",
      "weight": 60
      }

  ]
}
Request JSON Object:

Example response:

Response:

Similar to GET weighted distribution instance method response.

Status Codes:

Configuration Information for Hunt Group Management

In the POST API, when creating an hunt group, it is possible to configure APIO to generate automatically the service user ID according to a specific rule.

The APIO behaviour for the hunt group automatic service user ID generation is controlled by the following setting:

"AUTOMATIC_ID_RULES": {
    "SUID_HUNT_GROUP_AUTO_GENERATE": true,
    "SUID_HUNT_GROUP_RULE": "{{group_id}}_hg{{RND_4}}@{{domain}}"
}
Settings description:

  • SUID_HUNT_GROUP_AUTO_GENERATE: APIO will enable the auto-generation of hunt group service ids. Default is False, it must be set to True to have this feature working.

  • SUID_HUNT_GROUP_RULE: the formatting rule for the hunt group service user id. Default is “{{group_id}}_hg{{RND_4}}@{{domain}}”.

If the service user id number is built using the phone number in the generation rule, it is possible to configure APIO to change the service user id according to phone number modification on PUT request.

The APIO behaviour for the hunt group automatic service user id modification is controlled by the following setting:

"AUTOMATIC_ID_RULES": {
     "SERVICE_USERS_UPDATE_ID_PHONE_NUMBER": true
 }
Settings description:

  • SERVICE_USERS_UPDATE_ID_PHONE_NUMBER: APIO will enable the auto-update of hunt group service ids. Default is False, it must be set to have this feature working with phone numbers based service user ids and containing any of “{{phone_number_e164}}”, “{{country_code}}” or “{{national_no_0}}” placeholders in id generation rule.

The formatting of the phone Number in the List answer is controlled by the following settings:

"GROUP_NUMBERS_USE_CC_CLI": false
With following parameters:

  • GROUP_NUMBERS_USE_CC_CLI, the OCI documentation says explicitly the numbers will be returned in E164. But it has been reported that sometimes it is not the case, and we have no info from Cisco about this. This parameter is used in some APIs (in this page the answer of the GET Hunt Groups List) to implement a workaround that will assume that the number is in national format if same country code as Grouo CLi. It is based on observations and not on Cisco doc. Therefore toi be used carefully