Ping the CallTools System for Available Queue Agents – CallTools

This guide is in place to assist with pinging the CallTools platform to see if there are any available agents in a queue that can take inbound calls to the platform. This is helpful for many use cases including lead vendors or 3rd parties that are looking to send transfers to available agents on CallTools.

We will be using the Agent Statuses API which is documented in Swagger for reference. To get to the official endpoint documentation please login to your CallTools Account and visit Integrations then API Docs.

Once logged into Swagger search for the Agent Statuses Section.

Prerequisites

Prior to continuing with the guide below you will want to identify the variables that will be used for the GET request so that when pinging the system the proper information will be returned.

Queue ID

To get the proper Queue ID your agents will be members of please do the following.

1) Click "Contact Center"

2) Click "Queues"

3) Next to the Queue you want to ping click the 3 dots under "Controls" and then click "Settings"

4) Once on this page the Queue ID will be the last variable of the webpage in the URL of that page. Save this as this is the ID for the Queue in later steps

Login URL / Silo

The login URL is what you use each time you login to the CallTools system. This can be found in your address bar when logged into any page of the CallTools System.

Agent Status ID

This is the status you will want to ping to ensure the agent is Available and ready to take an inbound call in the system.

1) Click on Contact Center and then Agent Statuses

2) Take note of the ID of the Available Status

1. Understand the Components of the URL

The provided URL has several components:

Variables Breakdown

Base URL:
- https://east-2.calltools.io/api/agentstatuses/
- This is the main endpoint for querying agent statuses. The subdomain (east-2) may vary depending on the client’s specific environment or server region.
Query Parameters:
- queue=5457:
  - Identifies the specific queue being queried. Each client may have different queue IDs depending on how they have set up their system.
- agent_status_id=20561:
  - Represents the status ID of the agents being queried. For example, this could map to "Ready," "Busy," or other custom statuses defined in the CallTools system.
- ready=true:
  - A boolean flag indicating whether to filter for agents marked as "ready" (i.e., available for calls). Setting this to false would return agents who are not ready.

2. Authentication

To access the CallTools API, an Authorization header is required. Without this, the API call will fail.

Header Format

Key: Authorization
Value: Token APIKEYHERE
- Replace APIKEYHERE with the unique API key provided to your organization.

3. Steps to Ping the System

Follow these steps to send a request to the CallTools API:

Step 1: Determine the API URL

Confirm the base URL for your account (e.g., https://east-2.calltools.io).
Identify the appropriate queue and agent_status_id values for your query.

Step 2: Set Up the API Request

Choose a method to make the API call (e.g., Postman, Python script, or any HTTP client).

Step 3: Configure the Headers

Add the Authorization header with your API key:

plaintext

Authorization: Token APIKEYHERE

Step 4: Build the Full URL

Construct the full URL, including query parameters:

ruby

https://<subdomain>.calltools.io/api/agentstatuses/?queue=<queue_id>&agent_status_id=<status_id>&ready=true
- Replace <subdomain> with your assigned region.
- Replace <queue_id> and <status_id> with your specific values.

Step 5: Send the Request

Use an HTTP GET method to send the request.
Example using curl:

bash

curl -X GET "https://east-2.calltools.io/api/agentstatuses/?queue=5457&agent_status_id=20561&ready=true" \ -H "Authorization: Token APIKEYHERE"

Step 6: Handle the Response

The API will return a JSON object with agent statuses. For example:

json

{ "agents": [ { "id": 101, "name": "John Doe", "status": "Ready" }, { "id": 102, "name": "Jane Smith", "status": "Busy" } ] }
Parse the response to extract the information you need.

4. Testing and Error Handling

Test the API Key:
- Verify that your API key is valid and correctly added to the Authorization header.
Handle Common Errors:
- 401 Unauthorized: Check if the API key is correct and active.
- 404 Not Found: Verify the base URL and resource path.
- 400 Bad Request: Ensure all required query parameters are included.
Log Results:
- Log both successful and failed responses for debugging purposes.

5. Example Script (Python)

Here’s a simple Python script using the requests library:

python

import requests

# API Details
base_url = "https://east-2.calltools.io/api/agentstatuses/"
params = {
    "queue": 5457,
    "agent_status_id": 20561,
    "ready": "true"
}
headers = {
    "Authorization": "Token APIKEYHERE"
}

# Send the request
response = requests.get(base_url, headers=headers, params=params)

# Handle the response
if response.status_code == 200:
    data = response.json()
    print("Available Agents:", data)
else:
    print(f"Error {response.status_code}: {response.text}")

6. Understanding the Response Structure

The response from the CallTools API contains details about agents in the specified queue and their statuses. Below is an example response with placeholder values for agent IDs and names.

Example Response

json

{
    "count": 5,
    "next": null,
    "previous": null,
    "results": [
        {
            "app_user": "dummy-user-1",
            "full_name": "Agent One",
            "account_id": 12345,
            "agent_status": 20561,
            "agent_status_modified_on": "2025-01-14T18:05:23.008142Z",
            "priority": 0,
            "ready_since": "2025-01-14T18:01:02Z",
            "ready": true,
            "web_phone_status": "Registered",
            "last_call_on": "2025-01-14T18:00:48Z",
            "logged_in_since": "2025-01-14T14:30:49.189901Z",
            "live_calls_count": 0,
            "calls": 32,
            "calls_outbound": 5,
            "calls_inbound": 27,
            "calls_under_1min": 18,
            "calls_over_5min": 10
        },
        {
            "app_user": "dummy-user-2",
            "full_name": "Agent Two",
            "account_id": 12345,
            "agent_status": 20561,
            "agent_status_modified_on": "2025-01-14T18:00:43.614238Z",
            "priority": 0,
            "ready_since": "2025-01-14T17:59:14Z",
            "ready": true,
            "web_phone_status": "Registered",
            "last_call_on": "2025-01-14T17:56:28Z",
            "logged_in_since": "2025-01-14T17:16:11.103654Z",
            "live_calls_count": 0,
            "calls": 25,
            "calls_outbound": 2,
            "calls_inbound": 23,
            "calls_under_1min": 15,
            "calls_over_5min": 4
        }
    ]
}

7. Key Fields in the Response

count: Total number of agents matching the query criteria (e.g., ready=true).
results: A list of agents, each represented by an object containing detailed information.

Fields for Each Agent:

app_user: Unique identifier for the agent.
full_name: Name of the agent.
account_id: Identifier for the account.
agent_status: Current status ID of the agent.
agent_status_modified_on: Timestamp of when the agent's status was last updated.
priority: Queue priority assigned to the agent (if applicable).
ready_since: Timestamp indicating when the agent became "ready."
ready: Boolean indicating whether the agent is available.
web_phone_status: Status of the agent's phone connection (e.g., Registered).
last_call_on: Timestamp of the agent's last call.
logged_in_since: Timestamp of when the agent logged in.
live_calls_count: Number of calls currently handled by the agent.
calls: Total calls handled by the agent during the session.
calls_outbound: Outbound calls made.
calls_inbound: Inbound calls received.
calls_under_1min: Number of calls lasting under one minute.
calls_over_5min: Number of calls lasting over five minutes.

If you have any questions please contact integrations@calltools.com