Agents
An agent is an extension that answers the calls of one or more queues. These endpoints manage queue agents: log an agent in or out of one or more queues, pause/unpause an agent (a paused agent stays logged in but temporarily stops receiving queue calls), and get an agent's activity report — logged time, pauses, adherence and per-queue call statistics.
The account is normally implied by your API key. If your key gives
access to several accounts, add an account parameter to select one.
The POST endpoints below expect a JSON body (send the header
Content-Type: application/json), because queue_names is a list.
Log an agent in
Log an agent (an extension) into one or more queues.
POST https://api.ubity.com/agent/<extension>/login
| Parameter | Description |
|---|---|
| key | Your Ubity API key |
| queue_names | The list of queue names to log the agent into |
| lang | The agent's language (ie. 'en', 'fr') |
% curl -X POST -H "Accept: application/json;version=0" -H "Content-Type: application/json" \
-d '{"queue_names": ["myqueue-QQQQ"], "lang": "en"}' \
"https://api.ubity.com/agent/101/login?key=KKKK"
{
"api_key": "KKKK",
"code": 200,
"diagnostic": "Success",
"mode": "normal",
"stamp": "2026-08-18 10:00",
"url": "https://api.ubity.com/agent/101/login?key=KKKK",
"version": 0
}
Log an agent out
POST https://api.ubity.com/agent/<extension>/logout
| Parameter | Description |
|---|---|
| key | Your Ubity API key |
| queue_names | The list of queue names to log the agent out of |
% curl -X POST -H "Accept: application/json;version=0" -H "Content-Type: application/json" \
-d '{"queue_names": ["myqueue-QQQQ"]}' \
"https://api.ubity.com/agent/101/logout?key=KKKK"
Pause an agent
A paused agent stays logged in the queues but does not receive queue calls.
POST https://api.ubity.com/agent/<extension>/pause
| Parameter | Description |
|---|---|
| key | Your Ubity API key |
| queue_names | The list of queue names in which to pause the agent |
| reason | The pause reason (free text, ie. 'lunch') |
% curl -X POST -H "Accept: application/json;version=0" -H "Content-Type: application/json" \
-d '{"queue_names": ["myqueue-QQQQ"], "reason": "lunch"}' \
"https://api.ubity.com/agent/101/pause?key=KKKK"
Unpause an agent
POST https://api.ubity.com/agent/<extension>/unpause
| Parameter | Description |
|---|---|
| key | Your Ubity API key |
| queue_names | The list of queue names in which to unpause the agent |
% curl -X POST -H "Accept: application/json;version=0" -H "Content-Type: application/json" \
-d '{"queue_names": ["myqueue-QQQQ"]}' \
"https://api.ubity.com/agent/101/unpause?key=KKKK"
Get an agent's activity
GET https://api.ubity.com/agent/<extension>
| Parameter | Description |
|---|---|
| key | Your Ubity API key |
| period | (optional) 'live' (today, default), 'day' (yesterday), 'week' or 'month' |
| dashboard | (optional) '1' or 'true' to get the extended dashboard report (queues, warnings, ...) |
The reply contains:
| Field | Description |
|---|---|
| activity | The agent's activity: paused state, adherence, logged duration, ... |
| fullname | The agent's full name |
| callerid_name | The agent's caller ID name |
| callerid_num | The agent's caller ID number |
With dashboard=1, the reply also contains the per-queue details
(queues), the login/adherence warnings, the covered period and the
outgoing calls statistics.
% curl -H "Accept: application/json;version=0" "https://api.ubity.com/agent/101?key=KKKK&period=week"