Tell the platform whether an agent can take the next call. setAgentState is the one CSTA verb that moves an agent through the work states a contact center runs on — logged on, ready, not-ready (with a reason), after-call-work, and logged off. The distributor only offers queued calls to agents who are ready, so this verb is what actually gates delivery. Drive it from your own agent desktop, a workforce-management integration, or a supervisor tool over the engine-native CSTA control leg — the same connection your app already uses for call control and routing. This is the ECMA CSTA (ECMA-269) Set Agent State operation, exposed as the wire verb setAgentState. It needs the agent_state scope on your CTI token; a token without that scope has the verb refused. See CTI Overview for how to connect and mint a scoped token.

​
The agent workstation model

An agent is a routable identity (a skill member) that the ACD can offer calls to. A workstation is the endpoint the agent is answering on — a browser softphone or a real SIP deskphone. login associates the two: it puts the agent on shift at a workstation and makes them eligible for the skills they belong to. Everything after that is a work-state change on that logged-on agent. The distributor keeps a live view of every agent’s state and picks only from the ready pool. Moving an agent out of ready removes them from selection immediately; moving them back in makes them a candidate on the next pass. That is the whole contract between this verb and the built-in ACD.
Wire stateCSTA agent modeOffered ACD work?When you set it
loginLogged OnAfter → readyAgent starts a shift and binds to a workstation
readyReady / AvailableYesAgent is available for the next queued call
not-readyNot Ready (+ aux)NoBreak, lunch, training, coaching — carry an auxReason
after-call-workWork Not Ready (ACW)NoWrap-up (disposition, notes) after a call clears
logoutLogged OffNoEnd of shift — removed from all skills
login makes the agent eligible but does not by itself start delivering calls — set ready explicitly when the agent is actually at the keyboard. This mirrors real ACD ergonomics, where “logged on” and “available” are distinct so an agent can log in, read handover notes, and only then go ready.

​
setAgentState

​
agentId
string
required
The agent identity to move. This is the ACD agent id (a skill member), not the workstation or SIP AOR. Tenant-checked against your token’s workspace.
​
state
enum
required
One of login, logout, ready, not-ready, after-call-work.
​
auxReason
string
A reason code for not-ready (e.g. lunch, break, training, meeting). Free-form and reporting-only — it does not change routing, it just labels why the agent is unavailable so supervisors and wallboards can break down idle time. Ignored for the other states.
Every verb is request/reply and correlated, so you get an acknowledgement (or a typed error — wrong scope, unknown agent, agent not logged on) for each call. State transitions that the distributor observes also surface as CSTA events on the cti event track; subscribe it if you’re building a supervisor view (see Routing & Events).

​
Move an agent through a shift

The control leg speaks length-prefixed, tab-separated <verb>\t<args-json> lines (the first line authenticates with your scoped CTI token). You can send those frames directly, or use the CTI client from your SDK, which wraps them.
1

Log the agent on at their workstation

Bind the agent to the endpoint they’ll answer on. After this they belong to their skills but are not yet offered calls.
2

Go ready

Put the agent into the delivery pool. The next queued call for one of their skills can now be offered to them.
3

Step away with a reason

On a break, set not-ready with an auxReason. The distributor stops offering calls; the reason code drives idle-time reporting.
4

Wrap up after a call

When a call clears, set after-call-work so the agent can disposition it without a new call landing mid-wrap-up. Return to ready when done.
5

Log off at end of shift

logout removes the agent from every skill and frees the workstation.
# Each line: <verb>\t<args-json>, length-prefixed, reply correlated by request.
setAgentState	{"agentId":"agent-1007","state":"login"}
setAgentState	{"agentId":"agent-1007","state":"ready"}
setAgentState	{"agentId":"agent-1007","state":"not-ready","auxReason":"lunch"}
setAgentState	{"agentId":"agent-1007","state":"after-call-work"}
setAgentState	{"agentId":"agent-1007","state":"ready"}
setAgentState	{"agentId":"agent-1007","state":"logout"}

import { Cti } from "@telequick/sdk/cti";

// `token` carries the `agent_state` scope (see the CTI Overview).
const cti = await Cti.connect({
  url: "wss://<workspace-id>.webrtc.telequick.dev/cti",
  token,
});

const agentId = "agent-1007";

await cti.setAgentState({ agentId, state: "login" });
await cti.setAgentState({ agentId, state: "ready" });

// Break — carry a reason for reporting.
await cti.setAgentState({ agentId, state: "not-ready", auxReason: "lunch" });

// A call just cleared: wrap up, then go ready again.
await cti.setAgentState({ agentId, state: "after-call-work" });
await cti.setAgentState({ agentId, state: "ready" });

await cti.setAgentState({ agentId, state: "logout" });

from telequick.cti import Cti

cti = Cti.connect(
    url="wss://<workspace-id>.webrtc.telequick.dev/cti",
    token=token,  # scope: agent_state
)

agent_id = "agent-1007"

cti.set_agent_state(agent_id=agent_id, state="login")
cti.set_agent_state(agent_id=agent_id, state="ready")

cti.set_agent_state(agent_id=agent_id, state="not-ready", aux_reason="lunch")

cti.set_agent_state(agent_id=agent_id, state="after-call-work")
cti.set_agent_state(agent_id=agent_id, state="ready")

cti.set_agent_state(agent_id=agent_id, state="logout")

​
How state drives delivery

When a call queues to a skill, the distributor picks from that skill’s ready members using the skill’s algorithm (expected-agent-delay / most-idle-agent, round-robin, and the other Avaya-style options described in PBX & ACD). An agent in not-ready, after-call-work, or logout is never a candidate; an agent already on a call isn’t offered a second one. If a picked agent doesn’t accept in time, the offer re-queues (RONA) and the picker moves on — so keeping state honest is what keeps queues flowing.
The platform does not force agents into after-call-work for you — your desktop sets it explicitly after a call clears. If you want automatic wrap-up, set after-call-work from your cleared event handler on the CSTA event track, then transition back to ready when the agent finishes.
Two surfaces, one model. This verb is the engine twin of the state control built into the contact-center console at agent.telequick.dev — the console drives its own agents through exactly these states. Use the CSTA verb when an external app (your CRM desktop, a WFM tool, an ISV integration) owns the agent’s presence instead. The console and the verb API move the same agents through the same distributor. See Contact-center platforms.
The same ready / not-ready model gates text work too. A human agent offered conversations from the embedded chat widget (<telequick-chat>) is only routed chats while ready, and one ready agent can carry several concurrent chats — so a single presence state governs an agent across voice and chat.

​
Honest status

  • setAgentState over the CSTA control leg — shipped, with agent_state scope enforcement, and verified moving agents across nodes in a multi-node deployment.
  • login / ready / not-ready / after-call-work / logout — all drive the distributor’s ready pool as described.
  • auxReason — accepted and carried into reporting; it is a label, not a routing input (a reason code never changes which agent is picked).
  • Automatic ACW entry on call clear — not automatic; set it from your cleared handler if you want it (see the note above).

CTI Overview

Connect the control leg, mint a scoped CTI token, and read the framing.

Routing & Events

Register as a route point and subscribe the CSTA event track.

Call Control

Make, hold, transfer, consult, DTMF, and clear the calls agents handle.

PBX & ACD

Skills, queues, and how the distributor picks from the ready pool.

Contact-center platforms

Build a full agent desktop on top of the CSTA verbs.

High availability

Keep agent state and routing alive across node failures.