Departments Live

Departments are routing groups. A conversation routed to a department is visible to every agent in that department; the first to claim it (or whoever round-robin picks) becomes the assignee. Internally the table is called groups; the UI and these docs use the word "department".

List departments

Cursor-paginated list of departments in the workspace. Most workspaces have under a dozen.

Code samples

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

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

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

require "net/http"
require "json"
uri = URI("https://app.message.com/api/v1/departments")
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
departments = JSON.parse(res.body)["departments"]

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

Get one department

Full department record including the current member roster.

{
  "id": "uuid",
  "version": 2,
  "name": "Billing",
  "slug": "billing",
  "color": "#22C55E",
  "routingStrategy": "round_robin",
  "memberAgentIds": ["uuid-a", "uuid-b"],
  "businessHoursOverride": null,
  "createdAt": "2026-01-04T12:00:00Z"
}

Create a department

Creates a department. Admin-only.

{
  "name": "Billing",
  "color": "#22C55E",
  "routingStrategy": "round_robin",
  "memberAgentIds": ["uuid-a", "uuid-b"]
}

Update a department

Edit name, colour, routing strategy. Requires expectedVersion.

Manage members

Add or remove a single agent. These exist alongside PATCH for surgical membership changes that do not require knowing the full current list.

Delete a department

Open conversations currently routed to the department fall back to the workspace default queue. Closed conversations keep the groupId field as a historical record; the resolved department label may show as "(deleted)".

Errors

Common pitfalls

• Confusing departments with channels. Channels are chat, ticket, call (medium). Departments are routing groups (Sales, Support, Billing). An agent on Support can still handle a phone call.
• Treating membership as exclusive. Agents belong to many departments. There is no primary department.
• Forgetting business-hours overrides. A department can have its own hours; outside hours the queue still receives conversations but does not page anyone.