Agents

Endpoints for listing and inviting agents (team members) in a workspace.

Overview

Agents are the team members who handle conversations and tickets within a workspace. An agent is a join entity between a User (the person who authenticates) and a Tenant (the workspace). One user can be an agent in multiple workspaces, and one workspace can have many agents.

Each agent has a role within their workspace: admin (full access including settings and billing) or agent (can handle conversations and tickets but cannot modify workspace settings).

Endpoints

List Agents

GET/agents

List all agents in the current workspace.

Auth: Workspace token (admin or agent)

Response 200
{
  "data": [
    {
      "id": "agt_abc123",
      "userId": "usr_def456",
      "fullName": "Sarah Agent",
      "email": "[email protected]",
      "role": "admin",
      "status": "active",
      "avatarUrl": null,
      "lastSeenAt": "2024-01-15T16:45:00Z",
      "createdAt": "2024-01-01T09:00:00Z"
    },
    {
      "id": "agt_xyz789",
      "userId": "usr_ghi012",
      "fullName": "Mike Support",
      "email": "[email protected]",
      "role": "agent",
      "status": "active",
      "avatarUrl": "https://cdn.zapticket.app/avatars/agt_xyz789.jpg",
      "lastSeenAt": "2024-01-15T16:30:00Z",
      "createdAt": "2024-01-05T11:00:00Z"
    },
    {
      "id": "agt_pending01",
      "userId": null,
      "fullName": null,
      "email": "[email protected]",
      "role": "agent",
      "status": "pending",
      "avatarUrl": null,
      "lastSeenAt": null,
      "createdAt": "2024-01-14T08:00:00Z"
    }
  ]
}
💡Agents with status: "pending" have been invited but haven't accepted yet. Their userId and fullName will be null until they register or link their existing account.

Invite Agent

POST/agents

Invite a new agent to the workspace by email. Sends an invitation email.

Auth: Workspace token (admin only)

Request Body
{
  "email": "[email protected]",
  "role": "agent"
}

The role field accepts "admin" or "agent". If omitted, defaults to "agent".

Response 201
{
  "id": "agt_new789",
  "email": "[email protected]",
  "role": "agent",
  "status": "pending",
  "invitedBy": "agt_abc123",
  "inviteExpiresAt": "2024-01-22T10:00:00Z",
  "createdAt": "2024-01-15T10:00:00Z"
}
⚠️Invitations expire after 7 days. If the invitee hasn't accepted, you can delete and re-send. Inviting an email that already has an active agent in this workspace returns 409 Conflict.

Agent Status Values

  • pending — Invited but hasn't accepted yet
  • active — Active agent, can handle conversations
  • deactivated — Removed from the workspace, cannot log in

Roles

  • admin — Full access: workspace settings, billing, agent management, plus all agent capabilities
  • agent — Can view/respond to conversations, manage tickets, view other agents. Cannot modify settings or invite new agents.