Queue Agent Actions

The Queue Agent Actions endpoints log an extension into or out of one queue, pause it with or without a reason, and unpause it. Each request changes only the selected extension's membership; it does not replace or rebuild the other queue members.

Endpoints

Action	Endpoint
Login	POST /queues/{queueId}/agents/{agentId}/login
Logout	POST /queues/{queueId}/agents/{agentId}/logout
Pause	POST /queues/{queueId}/agents/{agentId}/pause
Unpause	POST /queues/{queueId}/agents/{agentId}/unpause

Authentication and Identifiers

These endpoints require a writable full tenant or global API key. Read-only keys are rejected. The tenant query parameter is required and must exactly match the tenant code or tenant name; wildcard tenant selection is not accepted.

Value	Required	Description
queueId	Yes	The queue's internal ID (qu_id), not its dialable queue number.
agentId	Yes	The extension's internal ID (ex_id), not its extension number.
tenant	Yes	Exact tenant code or tenant name.
key	No, if using headers	The API key can be sent with X-API-Key, Authorization: Bearer, or the key query parameter.

Request Body

Login, logout, and unpause do not need a request body. A pause request accepts an optional JSON body:

{
  "reason": "Lunch"
}

The reason can contain up to 80 characters. Omit the body, send an empty object, or use an empty reason to pause without a reason. pausereason is accepted as a compatibility alias for reason; if both names are supplied, their values must match. A pause reason cannot be sent to the other actions.

Examples

Log In

curl -X POST \
  -H "X-API-Key: TENANT_API_KEY" \
  "https://pbx.example.com/pbx/openapi.php/queues/25/agents/101/login?tenant=CANISTRACCI"

Pause Without a Reason

curl -X POST \
  -H "X-API-Key: TENANT_API_KEY" \
  "https://pbx.example.com/pbx/openapi.php/queues/25/agents/101/pause?tenant=CANISTRACCI"

Pause With a Reason

curl -X POST \
  -H "X-API-Key: TENANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Lunch"}' \
  "https://pbx.example.com/pbx/openapi.php/queues/25/agents/101/pause?tenant=CANISTRACCI"

Unpause and Log Out

curl -X POST \
  -H "X-API-Key: TENANT_API_KEY" \
  "https://pbx.example.com/pbx/openapi.php/queues/25/agents/101/unpause?tenant=CANISTRACCI"

curl -X POST \
  -H "X-API-Key: TENANT_API_KEY" \
  "https://pbx.example.com/pbx/openapi.php/queues/25/agents/101/logout?tenant=CANISTRACCI"

Response

{
  "object": "queue_agent_action",
  "action": "pause",
  "status": "paused",
  "changed": true,
  "queue": {
    "id": 25,
    "number": "700",
    "name": "Support"
  },
  "agent": {
    "id": 101,
    "number": "100",
    "name": "Reception",
    "peer": "101"
  },
  "members": [
    {
      "membername": "100",
      "interface": "Local/AG-000-NF-101@fromotherpbx/n",
      "state_interface": "Custom:101",
      "member_device": "101",
      "penalty": 0,
      "paused": true,
      "pause_reason": "Lunch"
    }
  ],
  "pbx_refresh": "confirmed",
  "warnings": []
}

changed is false when the requested state was already active. Login and logout are idempotent. Pause and unpause are also idempotent after the agent is logged in; attempting either operation for an extension that is not a member of the queue returns HTTP 409.

pbx_refresh reports whether the live Asterisk refresh was confirmed. If the database action succeeds but the refresh cannot be confirmed, the request still returns the saved state with pbx_refresh set to failed and an explanation in warnings. Retrying the same action is safe and requests another refresh.

Behavior

• Login uses the queue's Agent Identification, Allow Call Optimization, and Ring Offline settings when constructing the member.
• A changed state writes the matching LOGIN, LOGOUT, PAUSE, or UNPAUSE queue log event and an activity audit entry.
• Unpause clears the stored pause reason.
• The final database state is checked before a successful response is returned.

Relevant Errors

HTTP status	Code	Description
400	exact_tenant_required	The tenant was omitted, does not exactly match the authenticated tenant, or uses a wildcard.
400	invalid_pause_reason	The pause reason is invalid or longer than 80 characters.
400	conflicting_pause_reason	reason and pausereason contain different values.
400	pause_reason_not_allowed	A reason was sent to login, logout, or unpause.
404	queue_not_found	The queue does not exist in the selected tenant.
409	agent_not_logged_in	Pause or unpause was requested before the extension was logged into the queue.
409	agent_peer_unavailable	The extension does not have a valid queue member device.
409	queue_agent_state_changed	A concurrent change prevented the requested final state from being confirmed; retry the request.
500	queue_agent_update_failed	The membership database operation failed.