The Inbox Availability API allows you to check whether users in a specific inbox are available to receive calls. When called with your unique API token and inbox ID, the API returns a list of agents in the inbox along with their routing eligibility and availability status.
This API is useful for monitoring call routing readiness, building custom dashboards, or integrating external systems that need to determine whether agents are currently able to accept calls.
This documentation outlines the required fields, examples, endpoints, and response structure to successfully utilize the Inbox Availability API.
Endpoint
This endpoint allows you to check the availability of users in an inbox.
GET /api/v1/webhook/ring-group/availability
Checking inbox availability
To check inbox availability, you need the following required fields:
api_token | Your Aloware account API token. |
ring_group_id | The ID of the inbox (ring group) that you want to check. |
Example GET URL
https://app.aloware.com/api/v1/webhook/ring-group/availability?api_token=[API_TOKEN]&ring_group_id=1
Example GET header
{
"Accept": "application/json",
"Content-Type": "application/json"
}
Response
HTTP 200 - a successful response returns a JSON object containing the list of users in the inbox and their availability results.
Example response
{
"test_results": [
{
"id": 2,
"failed_to_route": false,
"order": 0,
"name": "John Agent",
"email": "[email protected]",
"reasons": {
"is_active": true,
"takes_task_from_area_code": true,
"takes_task_in_state": true,
"takes_task_in_operating_hours": true,
"takes_call_within_concurrency_limit": true,
"takes_call_within_quota_limit": true,
"takes_call_within_duplication_period_limit": true,
"agent_answers_call": true,
"agent_accepts_call": true
},
"answer_by": "Browser / Apps",
"agent_status": "Accepting Calls"
},
{
"id": 3,
"failed_to_route": true,
"order": 1,
"name": "Jane Agent",
"email": "[email protected]",
"reasons": {
"is_active": true,
"takes_task_from_area_code": true,
"takes_task_in_state": true,
"takes_task_in_operating_hours": false,
"takes_call_within_concurrency_limit": true,
"takes_call_within_quota_limit": true,
"takes_call_within_duplication_period_limit": true,
"agent_answers_call": true,
"agent_accepts_call": true
},
"answer_by": "Phone Number",
"agent_status": "On Break"
}
],
"available_users_count": 1,
"unavailable_users_count": 1,
"total_users_count": 2
}
Response fields
test_results | An array of user objects containing the availability test results for each user in the inbox. |
available_users_count | The number of users currently able to receive calls. |
unavailable_users_count | The number of users who cannot receive calls. |
total_users_count | The total number of users configured in the inbox. |
failed_to_route | Boolean value indicating whether the system can route calls to the user.
|
agent_status | A human-readable description of the agent's current status (for example: Accepting Calls, On Break, Offline, or On Call). |
reasons | An object containing the results of the individual availability checks performed for the user. |
Detailed availability tests
Each user in the inbox undergoes multiple checks to determine whether they are eligible to receive calls.
No. | Rule | Field | Description |
1 | Agent active status |
| Checks whether the agent's account is active and not paused. |
2 | Area code coverage |
| Verifies whether the agent is configured to handle calls from the caller's area code. |
3 | Geographic coverage |
| Checks whether the agent is configured to handle calls from the caller's country and state. |
4 | Operating hours |
| Validates whether the current time falls within the agent's configured working hours. |
5 | Device capability |
| Ensures that the agent's configured device or setup can receive calls. |
6 | Agent availability status |
| Checks whether the agent's current status allows them to accept incoming calls. |
7 | Concurrency limits |
| Verifies that the agent has not exceeded the allowed number of simultaneous calls. |
Availability logic
A user is considered available only when all applicable tests return true.
If any test fails, the user will be marked as unavailable:
failed_to_route = true
Unavailable users will not receive calls routed from the inbox.
Validation errors
HTTP 400 – Validation failure
If a required parameter is missing, the API returns a validation error.
Example response:
{
"message": "The given data was invalid.",
"errors": {
"ring_group_id": [
"The inbox id field is required."
]
}
}HTTP 404 – Inbox not found
If the provided inbox ID does not exist, the API returns the following response:
{
"error": "Inbox not found."
}cURL example
curl --location --request GET \ 'https://app.aloware.com/api/v1/webhook/ring-group/availability?api_token=[API_TOKEN]&ring_group_id=1'
Make sure to replace [API_TOKEN] with your actual Aloware API token.