Capacity Groups

Capacity (also referred to as channels) defines the amount of concurrent calls phone.systems™ cloud PBX can handle. Internal, external, incoming and outgoing (all types) calls are counted.

Capacity groups scheme

By default, all channels on your account are shared across all your phone.systems Customers. Channels may also be grouped together into “Capacity groups” which can be applied to multiple different customers simultaneously. Additionally each customer in a capacity group can be configured to have a preferred capacity limit allowing you to set a maximum number of concurrent calls for a customer while still using a capacity group that is shared with other customers.

Important

The maximum amount of capacity (channels) that can be assigned to capacity groups is equal to the amount of channels ordered on your commercial account.

When a capacity group (or a single customer) reaches the configured capacity limit - new calls are rejected by the PBX system with the following reason:

Disconnect Code

Disconnect Reason

Internal Reason

480

Temporarily Unavailable

Insufficient channels

As soon as a channel becomes available, new calls start to connect as expected.

Additionally, the customer can configure a preferred rejection code (default is “480 Temporarily Unavailable”) which will be used for calls that are rejected due to channel insufficiency.

Note

Selecting a preferred rejection code has no impact on your capacity groups. Customers cannot apply any configuration changes to your capacity groups.

If capacity groups are not required they may be skipped and not specified while creating new customers. They will automatically use channels that are not assigned to any capacity group.

The following HTTP method(s) are available:

Relationship to other resources:

Name

Resource Type

Relationship Type

Updatable

Description

customer

customers

To-many

Yes

Customers that will be added to the capacity group

Hint

Relationships can be used with include and fields parameters if the method supports it.

Creating a Capacity Group

Use the HTTP POST method to create a new capacity group.

POST

/api/rest/public/operator/capacity_groups

Important

Customers that should be added to this capacity group must be specified as “relationships” in your request body.

This method supports Sparse fieldsets

Attributes:

Attribute

Value

Comment

Optional

Controlled via UI

name

Any string

Capacity group name

No

No

capacity

Any integer

The number of channels allocated for this capacity group

No

No

Request and Response examples:

http

POST /api/rest/public/operator/capacity_groups HTTP/1.1
Host: api.telecom.center
Content-Type: application/vnd.api+json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

{
  "data": {
    "type": "capacity_groups",
    "attributes": {
      "name": "testing",
      "capacity": 10
    },
    "relationships": {
      "customers": {
        "data": [
          {
            "id": "8844",
            "type": "customers"
          }
        ]
      }
    }
  }
}

curl

curl -i -X POST https://api.telecom.center/api/rest/public/operator/capacity_groups -H 'Content-Type: application/vnd.api+json' --data-raw '{"data": {"attributes": {"capacity": 10, "name": "testing"}, "relationships": {"customers": {"data": [{"id": "8844", "type": "customers"}]}}, "type": "capacity_groups"}}' --user username:password

response

HTTP/2 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "2c0d8da1-0738-47f0-97ce-31970b90008e",
    "type": "capacity_groups",
    "links": {
      "self": "https://api.telecom.center/api/rest/public/operator/capacity_groups/2c0d8da1-0738-47f0-97ce-31970b90008e"
    },
    "attributes": {
      "name": "testing",
      "capacity": 10
    },
    "relationships": {
      "customers": {
        "links": {
          "self": "https://api.telecom.center/api/rest/public/operator/capacity_groups/2c0d8da1-0738-47f0-97ce-31970b90008e/relationships/customers",
          "related": "https://api.telecom.center/api/rest/public/operator/capacity_groups/2c0d8da1-0738-47f0-97ce-31970b90008e/customers"
        }
      }
    },
    "meta": {
      "customers_count": 1
    }
  }
}

Fetching Capacity Groups

Use the HTTP GET method to retrieve a capacity group.

GET

/api/rest/public/operator/capacity_groups

This method supports Sorting, Pagination and Sparse fieldsets

Other supported parameters:

Parameter

Value

Description

filter[name]

string

Used to filter results by capacity group name

http

GET /api/rest/public/operator/capacity_groups HTTP/1.1
Host: api.telecom.center
Content-Type: application/vnd.api+json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

curl

curl -i https://api.telecom.center/api/rest/public/operator/capacity_groups -H 'Content-Type: application/vnd.api+json' --user username:password

response

HTTP/2 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "b62f258e-bdbc-4ffa-bb6d-6e2417adad29",
      "type": "capacity_groups",
      "links": {
        "self": "https://api.telecom.center/api/rest/public/operator/capacity_groups/b62f258e-bdbc-4ffa-bb6d-6e2417adad29"
      },
      "attributes": {
        "name": "Empty group",
        "capacity": 0
      },
      "relationships": {
        "customers": {
          "links": {
            "self": "https://api.telecom.center/api/rest/public/operator/capacity_groups/b62f258e-bdbc-4ffa-bb6d-6e2417adad29/relationships/customers",
            "related": "https://api.telecom.center/api/rest/public/operator/capacity_groups/b62f258e-bdbc-4ffa-bb6d-6e2417adad29/customers"
          }
        }
      },
      "meta": {
        "customers_count": 0
      }
    },
    {
      "id": "f6b66a02-7e62-472b-80bb-a1943c7b0ba7",
      "type": "capacity_groups",
      "links": {
        "self": "https://api.telecom.center/api/rest/public/operator/capacity_groups/f6b66a02-7e62-472b-80bb-a1943c7b0ba7"
      },
      "attributes": {
        "name": "Test group",
        "capacity": 22
      },
      "relationships": {
        "customers": {
          "links": {
            "self": "https://api.telecom.center/api/rest/public/operator/capacity_groups/f6b66a02-7e62-472b-80bb-a1943c7b0ba7/relationships/customers",
            "related": "https://api.telecom.center/api/rest/public/operator/capacity_groups/f6b66a02-7e62-472b-80bb-a1943c7b0ba7/customers"
          }
        }
      },
      "meta": {
        "customers_count": 10
      }
    }
  ],
  "meta": {
    "record_count": 2,
    "total_capacity": null,
    "assigned_capacity": 22
  },
  "links": {
    "first": "https://api.telecom.center/api/rest/public/operator/capacity_groups?page%5Bnumber%5D=1&page%5Bsize%5D=50",
    "last": "https://api.telecom.center/api/rest/public/operator/capacity_groups?page%5Bnumber%5D=1&page%5Bsize%5D=50"
  }
}

The response body contains an array of all created capacity groups as well as meta for each responded capacity group.

Meta consists of two attributes:

Attribute

Description

total_capacity

The total amount of channels available on your account

assigned_capacity

The amount of channels assigned to all capacity groups

Additionally, a capacity group ID may be included to the request URL in order to retrieve a single capacity group. Example below:

GET

/api/rest/public/operator/capacity_groups/{id}

Updating a Capacity Group

Use the HTTP PATCH method to update a capacity group.

PATCH

/api/rest/public/operator/capacity_groups/{id}

This method supports Sparse fieldsets and Inclusion of related resources

Attributes:

Attribute

Value

Comment

Optional

Controlled via UI

name

Any string

Capacity group name

No

No

capacity

Any integer

The amount of channels allocated for this capacity group

No

No

http

PATCH /api/rest/public/operator/capacity_groups/{id} HTTP/1.1
Host: api.telecom.center
Content-Type: application/vnd.api+json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

{
  "data": {
    "id": "b62f258e-bdbc-4ffa-bb6d-6e2417adad29",
    "type": "capacity_groups",
    "attributes": {
      "name": "Updated",
      "capacity": 23
    },
    "relationships": {
      "customers": {
        "data": [
          {
            "id": "1849",
            "type": "customers"
          }
        ]
      }
    }
  }
}

curl

curl -i -X PATCH 'https://api.telecom.center/api/rest/public/operator/capacity_groups/{id}' -H 'Content-Type: application/vnd.api+json' --data-raw '{"data": {"attributes": {"capacity": 23, "name": "Updated"}, "id": "b62f258e-bdbc-4ffa-bb6d-6e2417adad29", "relationships": {"customers": {"data": [{"id": "1849", "type": "customers"}]}}, "type": "capacity_groups"}}' --user username:password

response

HTTP/2 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "b62f258e-bdbc-4ffa-bb6d-6e2417adad29",
    "type": "capacity_groups",
    "links": {
      "self": "https://api.telecom.center/api/rest/public/operator/capacity_groups/b62f258e-bdbc-4ffa-bb6d-6e2417adad29"
    },
    "attributes": {
      "name": "Updated",
      "capacity": 23
    },
    "relationships": {
      "customers": {
        "links": {
          "self": "https://api.telecom.center/api/rest/public/operator/capacity_groups/b62f258e-bdbc-4ffa-bb6d-6e2417adad29/relationships/customers",
          "related": "https://api.telecom.center/api/rest/public/operator/capacity_groups/b62f258e-bdbc-4ffa-bb6d-6e2417adad29/customers"
        }
      }
    },
    "meta": {
      "customers_count": 1
    }
  }
}

Deleting a Capacity Group

Use the HTTP DELETE method to delete a capacity group.

DELETE

/api/rest/public/operator/capacity_groups/{id}

Note

Deleting a capacity group will move all related customers to the “Unassigned capacity group” which will automatically use all available channels that are not assigned to any capacity group.

Request and Response examples:

http

DELETE /api/rest/public/operator/capacity_groups/123 HTTP/1.1
Host: api.telecom.center
Content-Type: application/vnd.api+json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

curl

curl -i -X DELETE https://api.telecom.center/api/rest/public/operator/capacity_groups/123 -H 'Content-Type: application/vnd.api+json' --user username:password

response

HTTP/2 204 No Content
Content-Type: application/vnd.api+json