Agents API

Invite teammates and manage individual product access, departments, and roles.

Authentication and management scope

These dashboard endpoints require an authenticated agent session JWT in Authorization: Bearer. A Verify, messaging, or MCP connection key does not grant access to them. Requests stay within the authenticated workspace.

Admins manage workspace members. Supervisors can manage ordinary agents only within their own department and permission boundaries; they cannot grant access they do not have. Agents use the self-service profile endpoints rather than the team-management endpoint.

List and read agents

GET /api/v1/agents returns { agents: [...] }, excluding the internal AI identity. The list is not cursor-paginated and has no role, status or department query filter. GET /api/v1/agents/:id reads one member. Private fields depend on the caller’s management permissions.

List and read agents

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

Invite a teammate

POST /api/v1/agents/invite requires email, name (1–120 characters) and role (admin, supervisor or agent). Optional groupIds assigns departments. channels accepts chats, tickets, calls and imessage; it defaults to chats when omitted. Optional accessGrants controls individual capabilities. Pending invitations reserve a seat. Invite creation can fail when seat capacity is exhausted.

The invite also supports canTransfer, canQuickResolve, inboxScope (own_departments or all), createExtension and businessHoursRuleId. Use the Team agents screen to review access before granting it.

Invite a teammate

curl 'https://app.message.com/api/v1/agents/invite' \
  -H 'Authorization: Bearer YOUR_AGENT_JWT' \
  -H 'Content-Type: application/json' \
  --data '{"email":"[email protected]","name":"Alex","role":"agent","channels":["tickets"]}'

Update individual access

PATCH /api/v1/agents/:id supports name, email, role, status, channels, accessGrants, groupIds or departments, workHours, canTransfer, canQuickResolve and inboxScope. Supervisor edits are constrained by the caller’s own access. Self-service name and avatar changes belong on PATCH /api/v1/me/profile.

Availability

POST /api/v1/me/status sets the calling agent’s status to available, away or offline. Availability alone does not grant product or department access.

Resend or remove an invitation

POST /api/v1/agents/:id/resend-invite sends a new invitation to an eligible unjoined member. DELETE /api/v1/agents/:id/invitation removes an unaccepted invitation. Management scope and seat checks still apply. Do not use resend as a way to reset a joined member’s password.

Deactivate a member

DELETE /api/v1/agents/:id disables access without erasing conversation history. The current caller and workspace owner are protected. Re-invitation is the supported route for a deactivated, unjoined identity. Message Team subscription seats are managed separately from the shared customer-product allowance.

Errors

Handle 400 invalid_body and protected-member errors, 403 agent_management_forbidden, 404 not_found and 409 email_already_exists. Inspect the response’s error and message instead of treating every failure as a temporary retry.