Agents

An agent here is a person — an org member with a handset mapped, who can be rung by click-to-call. Not an AI persona.

List agents

GET /api/agents · scope agents:read

{
  "agents": [
    {
      "id": 12,
      "user_id": 4,
      "name": "Arjun Rao",
      "email": "[email protected]",
      "role": "member",
      "phone_number": "+919876543210",
      "is_active": true
    }
  ]
}

user_id is the underlying account; id is the agent record. Calls are started with the agent id.

Available members

GET /api/agents/available-members — manager or above

{
  "members": [
    { "user_id": 1, "name": "Arjun Rao", "email": "[email protected]", "role": "admin" }
  ]
}

Org members who do not yet have an agent record — the candidate list when adding one. Without it you would be guessing which teammates are already set up.

Create an agent

POST /api/agents — manager or above

{
  "user_id": 4,
  "phone_number": "+919876543210"
}

Links an existing org member to a handset. The member must already exist — invite them through organization members first.

Update an agent

PATCH /api/agents/{id} — manager or above

Change the mapped number, or deactivate:

{ "phone_number": "+919876500000", "is_active": false }

An inactive agent stays configured but cannot take calls:

{ "detail": "that agent is inactive and can't take calls" }

Prefer deactivating over deleting when someone is on leave — it keeps their call history attributed.

Delete an agent

DELETE /api/agents/{id} — manager or above

Removes the agent record. The underlying user account is untouched.

Why these are role-gated

Reading the agent list needs only agents:read, so an integration can show who is available. Creating and modifying agents requires a manager session and refuses API keys — mapping a phone number decides where customer calls are routed, which is configuration rather than day-to-day work.

This is the same split as everywhere else in the platform: keys do the work, sessions change the setup. See Authentication.