Agents Live

Agents are the team members who handle conversations. Every agent has a role (admin, supervisor, agent), a channel scope, and zero or more department memberships. This API covers invite, edit, suspend, and remove.

List agents

Cursor-paginated list of agents in the workspace. Optional filters by role, status, and departmentId.

Code samples

curl 'https://app.message.com/api/v1/agents' \
  -H 'Authorization: Bearer YOUR_WORKSPACE_JWT'

const res = await fetch('https://app.message.com/api/v1/agents', {
  headers: { Authorization: 'Bearer ' + token }
});
const { agents } = await res.json();

import requests
r = requests.get(
    "https://app.message.com/api/v1/agents",
    headers={"Authorization": f"Bearer {token}"},
)
agents = r.json()["agents"]

require "net/http"
require "json"
uri = URI("https://app.message.com/api/v1/agents")
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  req = Net::HTTP::Get.new(uri)
  req["Authorization"] = "Bearer #{token}"
  http.request(req)
end
agents = JSON.parse(res.body)["agents"]

<?php
$ctx = stream_context_create([
  "http" => ["method" => "GET", "header" => "Authorization: Bearer $token"]
]);
$agents = json_decode(file_get_contents("https://app.message.com/api/v1/agents", false, $ctx), true)["agents"];

Get one agent

{
  "id": "uuid",
  "version": 5,
  "email": "[email protected]",
  "name": "Alex Lee",
  "role": "agent",
  "channels": ["chat", "ticket"],
  "departments": ["uuid-billing", "uuid-support"],
  "status": "available",
  "avatarUrl": "https://...",
  "suspendedAt": null,
  "createdAt": "2026-01-04T12:00:00Z"
}

Invite an agent

Sends an invitation email containing a one-time link the recipient uses to set their password. Pending invites count against the seat cap. Admin-only.

{
  "email": "[email protected]",
  "name": "Alex Lee",
  "role": "agent",
  "channels": ["chat", "ticket"],
  "departments": ["uuid-billing"]
}

Update an agent

Change role, channels, departments, or display name. Requires expectedVersion. Admins can edit anyone; supervisors can edit only their own department members; agents can edit only themselves (and only name + avatar).

Set status

Sets the calling agent's availability. Drives routing (only available agents receive new assignments) and presence indicators in the inbox.

{ "status": "away" }

Allowed values: available, away, offline.

Suspend / reinstate

Suspended agents cannot log in and disappear from routing. Their assigned conversations fall back to their departments. Reinstate is the inverse.

Remove an agent

Permanent removal. The agent record is retained in the audit log; their assigned conversations fall back to the department or workspace queue. Admin-only.

Errors

Common pitfalls

• Setting channels for admins. Ignored. Admins always see all channels.
• Reinstating after a seat change. If your plan dropped below the active agent count, reinstating returns 402 seat_limit_reached. Upgrade first.
• Looking for a password field. Passwords are set by the invitee via the invite link. There is no admin-set-password endpoint.