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.

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

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
← AI & AutomationAuto-Greeting →
Auto-Assign Configuration — Fiko Docs