Departments API

Create routing departments, manage members, and choose the workspace’s default department.

Permissions

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.

Authenticated agents can read departments. Changes require an admin. A department is distinct from a ticket queue or saved report view.

List and read departments

GET /api/v1/departments returns { departments: [...] } without cursor pagination. Each entry contains identity, name, slug, channels, memberCount, queueDepth and phone configuration. GET /api/v1/departments/:id returns the department and its members. Deleted departments are excluded.

Create a department

POST /api/v1/departments requires name (1–120 characters). Optional fields are slug, description, color, icon, timezone, workHours, channels, isDefault, agentIds, voicemailEnabled, voicemailGreetingId and mohAudioUrl. channels uses chats, tickets and calls. Member IDs must belong to the same workspace. Returns HTTP 201 with { department: {...} }.

Create a department

curl 'https://app.message.com/api/v1/departments' \
  -H 'Authorization: Bearer YOUR_AGENT_JWT' \
  -H 'Content-Type: application/json' \
  --data '{"name":"Support","channels":["chats","tickets"]}'

Update and membership

PATCH /api/v1/departments/:id updates the editable department fields. If agentIds is supplied, it replaces the membership list; omit it to leave membership unchanged. There is no expectedVersion field. POST /api/v1/departments/:id/members with { agentIds: [...] } adds members without replacing existing ones and returns added and totalMembers. DELETE /api/v1/departments/:id/members/:agentId removes one membership and returns HTTP 204.

Choose the default department

POST /api/v1/departments/:id/set-default promotes the target and returns { department: {...} }. Use this endpoint when replacing the existing default instead of setting isDefault on an update.

Delete safely

DELETE /api/v1/departments/:id soft-deletes a department and returns HTTP 204. The default cannot be deleted (400 cannot_delete_default). Departments with open or pending conversations return 400 department_has_conversations with openCount. Move or resolve those conversations first.

Handle errors

Invalid fields return 400 invalid_body. Foreign member IDs return 400 invalid_agent_id. Missing departments return 404 not_found. Creating a second default returns 409 default_already_exists.