message.comDevelopers
Developers/Tutorials/Route by department

Route conversations by department

Get conversations to the right team without anyone in the middle. Set up departments, assign agents, then route per channel: inbound addresses for tickets, DIDs for phone, a pre-chat selector or page-URL rules for chat.

Internally, departments are called groups in the API. The dashboard says Department; the field is groupId. See Department vs team.

1. Create departments

  1. Open app.message.com.
  2. Go to Settings → Team → Departments.
  3. Click Add department. Common starter set: Sales, Support, Billing.
  4. For each department, set a name and color (for the inbox lane).

2. Assign agents

Each agent belongs to one or more departments. Agents see only the departments they belong to (admins see everything). From an agent's profile:

  • Pick the departments to include.
  • Set the agent's role: agent, supervisor, or admin.
  • Set the channels they can handle: chats, tickets, calls.

3. Route tickets by inbound address

Each inbound address can route to a specific department. Examples:

Set this under Settings → Tickets → Inbound on each address.

4. Route calls by DID

Each phone number can route to a department. Set the routing strategy on the DID:

  • department. ring all available agents in that department.
  • all_agents. ring everyone.
  • specific_agent. ring one agent (PA line, exec line).

See Phone numbers API.

5. Route chat by pre-chat selection

For chat, show a department picker before the visitor sends the first message. The widget's pre-chat form supports a select field:

HTML
<script>
  window.MessageOnReady = function () {
    window.Message.update({
      preChatFields: [
        { name: "department", label: "How can we help?", type: "select",
          options: [
            { value: "sales", label: "Sales" },
            { value: "support", label: "Support" },
            { value: "billing", label: "Billing" }
          ]
        }
      ]
    });
  };
</script>

The selected value maps to a department via a rule under Settings → Chats → Routing → Pre-chat field mapping.

6. Route chat by page URL

Alternative: route by where the conversation starts. Examples:

  • Chats from /pricing or /sales → Sales.
  • Chats from /docs or /help → Support.
  • Chats from /billing or the in-app account page → Billing.

Configure under Settings → Chats → Routing → URL rules.

7. Verify

  1. From a private window, open /pricing and start a chat. Confirm it lands in Sales.
  2. Email [email protected]. Confirm the ticket lands in Billing.
  3. Call the support number. Confirm it rings Support agents.

Common pitfalls

  • Empty departments. If a department has no agents available, conversations stack up unhandled. Set a fallback department.
  • Cross-department transfers. Use the conversations transfer endpoint. Department transfers are instant (no 30s handshake).
  • Visitor sees Sales agent label after transfer to Support. Expected. The visitor sees one agent at a time. Internal transfers are invisible from the visitor side.
  • Mixed-role agents. A senior support engineer who is also on billing duty should belong to both departments. Agents are not single-department locked.

Next steps