Skip to main content

Auto-Assign Configuration

Auto-Assign is an intelligent chat distribution system that automatically assigns incoming chats to available agents based on configurable strategies. It ensures fair workload distribution, reduces manual assignment overhead, and improves response times for customers.

Key Benefits

  • Automatic distribution of chats to available agents
  • Multiple assignment strategies (round-robin, least-busy, random)
  • Queue management when all agents are busy
  • Real-time WebSocket notifications for agents
  • Seamless integration with Auto-Menu for group-based assignment

How Auto-Assign Works

Auto-Assign automatically triggers when a new chat is created or when a chat needs reassignment.

1

Chat Created

When a customer starts a new chat, the Auto-Assign system is triggered to find an available agent.

2

Check Auto-Menu Integration

If Auto-Menu is active, the system waits for the customer to select a group before assigning to an agent within that group.

3

Find Available Agents

The system queries all active agents (optionally filtered by group) to find eligible agents for assignment.

4

Apply Assignment Strategy

Based on the configured strategy (round-robin, least-busy, or random), the system selects the most appropriate agent.

5

Assign & Notify

The chat is assigned to the selected agent, and a real-time WebSocket notification is sent to inform them of the new chat.

When no agents are available: The chat is placed in a FIFO queue with status QUEUED. Admins receive notifications about queued chats and they are automatically assigned when agents become available.

Admin Role & Assignment

Admin and CS roles participate in auto-assign differently depending on whether your company has CS agents registered.

Company with CS agents

  • Only CS agents are included in the auto-assign pool
  • Admins are excluded from auto-assign and never receive chats automatically
  • Admins can use Take Over to manually claim any individual chat and reply to it
  • After handling, admins use Release to return the chat to the queue for CS agents

Admin-only company (no CS agents)

  • Admins are automatically included in the assignment pool
  • Incoming chats are assigned to admins using the configured strategy (round-robin, least-busy, random)
  • When an admin comes online, queued chats are drained to them automatically
  • Admins can release their assigned chats back to the queue at any time

Note: The check is based on whether CS agents are registered in the company, not whether they are currently online. If a company has CS agents but they are all offline, admins remain excluded from auto-assign and chats queue until a CS agent comes back online.

Assignment Strategies

Choose the strategy that best fits your team's workflow and customer support needs.

Round Robin

Sequential Rotation — assigns chats to agents in sequential order, rotating through the available agents list. Ensures equal distribution over time.

Strategy: "round_robin"
Order: A → B → C → A...
Use Case: Fair distribution

Least Busy

Workload Based — assigns to the agent with the fewest active chats. Automatically balances workload in real-time.

Strategy: "least_busy"
Logic: Count active chats
Assign: Agent with MIN count

Random

Random Selection — randomly assigns chats to any available agent. Simple and unpredictable distribution pattern.

Strategy: "random"
Logic: Random selection
Assign: Any available agent

Configuration Options

The Auto-Assign configuration page provides several sections to customize how chats are distributed. Access it from Automations → Auto-Assign.

Agent Capacity

Control the maximum number of concurrent chats each agent can handle.

  • Unlimited chats per agent — When enabled, agents can receive any number of chats without limit
  • Maximum chats per agent — When disabled, set a specific limit (1-100). Agents at capacity will not receive new assignments

Agent Chat Visibility

Control whether agents can see conversations that are not assigned to them.

  • Can view all chats (default) — Agents can see all chats in their channels, even ones not assigned to them. They cannot reply to or take over those chats.
  • Only assigned chats — Agents can only see the chats that are directly assigned to them. Unassigned and other agents' chats are hidden from their view.

This is a company-wide setting. Users with the Viewer role can see this setting but cannot change it.

Additional Settings

Configure reassignment behavior and group-based routing.

  • Auto-reassign when agent goes offline — Automatically reassign chats to other agents when an agent disconnects
  • Offline grace period (minutes) — Wait time before reassigning chats when an agent goes offline. Set to 0 for immediate reassignment
  • Group-based assignment — (Coming soon) Assign chats only to agents in the same group, requires Auto-Menu integration

Chat Re-balancing

Redistribute chats when new agents come online to optimize workload distribution.

  • Re-balance chats when agent comes online — Automatically redistribute idle chats from overloaded agents to newly online agents
  • Chat idle threshold (minutes) — Only rebalance chats with no messages for the specified duration to prevent interrupting active conversations

Auto-Close

Automatically close inactive chats to keep your chat list clean.

  • Auto-close inactive chats — Enable automatic closure of chats with no new messages for the specified period
  • Inactivity threshold (minutes) — Minimum 30 minutes, maximum 43,200 (30 days). Chats inactive for this long will be automatically closed

Queue Management

When all agents are busy or offline, incoming chats are placed in a FIFO (First In, First Out) queue.

Assignment Status Values

  • QUEUED — Waiting for available agent
  • ASSIGNED — Assigned to an agent
  • TAKEN_OVER — Admin took over from agent

Queue Behavior

  • Chats are queued in order received
  • Automatic assignment when agent becomes active
  • Admins can view all queued chats
  • Queue position shown in notifications

WebSocket Events

Auto-Assign uses WebSocket events to provide real-time updates to agents and admins.

CHAT_ASSIGNED→ Assigned agent + All admins

Sent when a chat is assigned to an agent. Contains chat details, member info, and last message preview.

CHAT_UNASSIGNED→ Previous agent

Sent when a chat is unassigned from an agent (went offline, reassigned, or taken over by admin).

CHAT_QUEUED→ All admins

Sent when a chat enters the queue because no agent is available.

CHAT_TAKEN_OVER→ Previous agent + Admin who took over

Sent when an admin takes over a chat from an agent.

AGENT_CHATS_REASSIGNED→ All agents/admins in company

Sent when an agent goes offline and their chats are bulk reassigned to other agents or queued.

CHAT_ASSIGNMENT_SYNC→ Connecting agent/admin

Sent when an agent/admin connects to sync all their assigned chats and queued chats (admins only).

Auto-Menu Integration

Sequential Flow: Auto-Menu → Auto-Assign
When both Auto-Menu and Auto-Assign are enabled, they work together to ensure chats are assigned to the right agent within the selected group.

1

Auto-Menu Shows First

When a chat is created, Auto-Menu shows the menu to the customer. Auto-Assign is PAUSED while waiting for menu selection.

2

Customer Selects Group

Customer selects an option, which sets the assignedGroupId on the chat based on the menu item's targetGroupId.

3

Auto-Assign Triggers with Filter

After group selection, the system publishes TRIGGER_AUTO_ASSIGN event with filterByGroupId to only consider agents within that group.

4

Agent Receives Chat

The selected agent (within the chosen group) receives the chat assignment notification.

If the customer doesn't select within the timeout (5 min), Auto-Assign proceeds without a group filter. If the customer types a message that doesn't match the menu, normal message flow continues.

Best Practices

Do

  • Use "least_busy" strategy for optimal load balancing
  • Ensure agents set status to ACTIVE when ready
  • Monitor queue regularly during peak hours
  • Combine with Auto-Menu for group-based routing
  • Test assignment flow before going live

Don't

  • Disable auto-assign during high-traffic periods
  • Leave agents in ACTIVE status when unavailable
  • Ignore queued chat notifications
  • Change strategy frequently without testing
  • Manually reassign without checking queue first

Troubleshooting

Chats not being assigned automatically?

  • Verify Auto-Assign is enabled in the configuration
  • Check that at least one agent has ACTIVE status
  • Ensure agents are members of the required group (if using Auto-Menu)
  • Check API endpoint response for any error messages

All chats going to queue?

  • Verify agents are set to ACTIVE status (not INACTIVE or OFFLINE)
  • Check if agents are in the correct group (when using Auto-Menu)
  • Review agent status update logic in your application

Agents not receiving WebSocket notifications?

  • Check WebSocket connection status in browser DevTools
  • Verify WebSocket event listeners are registered correctly
  • Check Redis connection for event broadcasting
  • Review server logs for WebSocket errors

Round-robin not rotating evenly?

  • Round-robin state is maintained in Redis cache
  • Cache may reset if Redis is restarted
  • Agents joining/leaving affects rotation order
  • Consider using "least_busy" for more dynamic balancing

Admins receiving chats automatically?

  • This is expected when your company has no CS agents registered — admins join the pool as a fallback
  • If you add CS agents to the company, admins will be excluded from auto-assign automatically on the next assignment
  • Admins can release any auto-assigned chat back to the queue using the Release button
← AI & AutomationAuto-Greeting →
Auto-Assign Configuration — Fiko Docs