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.

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:

GET /capacity_groups - For Fetching capacity groups
POST /capacity_groups - For Creating a capacity group
DELETE /capacity_groups/{id} - For Deleting a capacity group
PATCH /capacity_groups/{id} - For Updating a capacity group

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 -X GET 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