DEV Community

Nitin Suryawanshi
Nitin Suryawanshi

Posted on

Architecting a Multi-Agent WhatsApp Shared Inbox with WebSockets & Real-Time Routing

#javascript

Managing customer conversations across a distributed support or sales team on WhatsApp is inherently difficult using the standard mobile app. With multiple reps replying from one device or disconnected Web sessions, conversations get dropped, customers receive conflicting answers, and management has zero oversight into response SLAs.

To build an enterprise-grade multi-agent WhatsApp shared inbox, you need an architecture that decouples the Meta Cloud API connection from individual agents, synchronizing state via WebSockets in real time.

Core Architecture Components

A production multi-agent shared inbox system requires four key microservices:

  1. Meta Cloud API Gateway: Connects to WhatsApp Business API via secure webhooks, ingests inbound messages, and validates outbound delivery status.
  2. Real-Time State Hub (WebSocket / Redis Pub-Sub): Distributes incoming messages instantly to all connected agent browsers and synchronizes "agent typing" and "agent viewing" indicators.
  3. Collision Prevention & Lock Manager: Prevents two support agents from drafting responses to the same customer simultaneously.
  4. Conversational CRM Core: Stores conversation histories, tags, customer contact details, custom fields, and conversation stages.

Step 1: Real-Time Event Dispatch via WebSocket

When a new message arrives from Meta, the backend processes the webhook and publishes an event to Redis Pub/Sub. Connected WebSocket servers broadcast the event to authorized agents:

// Server-side WebSocket broadcast handler
interface ChatEvent {
  conversationId: string;
  senderPhone: string;
  messageText: string;
  timestamp: number;
}

redisSubscriber.subscribe("whatsapp_inbound_stream", (err) => {
  if (err) console.error("Redis subscription error:", err);
});

redisSubscriber.on("message", (channel, message) => {
  const event: ChatEvent = JSON.parse(message);

  // Broadcast to all active support agents viewing this team queue
  wsServer.clients.forEach((client) => {
    if (client.readyState === WebSocket.OPEN) {
      client.send(JSON.stringify({
        type: "INBOUND_MESSAGE",
        payload: event
      }));
    }
  });
});
Enter fullscreen mode Exit fullscreen mode

Step 2: Agent Collision Prevention (Soft Locking)

One of the biggest pain points in shared inboxes is "double replies"—when Agent A and Agent B both reply to the same customer at the same second.

We solve this using a soft lease pattern in Redis:

async function acquireConversationLock(conversationId: string, agentId: string): Promise<boolean> {
  const lockKey = `lock:conv:${conversationId}`;

  // Set lease for 30 seconds with heartbeat renewal
  const acquired = await redis.set(lockKey, agentId, "NX", "EX", 30);
  return acquired === "OK";
}
Enter fullscreen mode Exit fullscreen mode

When an agent focuses the reply textarea, the client acquires the lease. Other agents see an avatar indicator: "Sarah is currently drafting a reply..." and the input box is visually disabled until the lease expires or is released.

Step 3: Integrating AI Assist and Enterprise Routing

Manual agent assignment slows down response times. High-performing teams leverage automated triage:

  1. Autonomous AI First-Response: An AI model analyzes the question, retrieves relevant documentation, and drafts an instant response or resolves the ticket completely.
  2. Skill-Based Routing: Unresolved technical issues route directly to engineering support, while high-value purchase inquiries route to senior sales account executives.

Instead of developing and maintaining a complex WebSocket cluster, Redis locking framework, and Meta API integration from scratch, teams can deploy AI Soul Conversational CRM.

AI Soul provides a turnkey Multi-Agent Shared Team Inbox with built-in collision prevention, role-based access control, analytics dashboards, and an autonomous WhatsApp AI Chatbot Builder to handle 24/7 frontline support.

Key Takeaways

  • Decouple Meta Webhooks: Always process Meta webhooks asynchronously to stay under the 3-second SLA.
  • Implement Heartbeat Locks: Prevent agent collision by utilizing short-lived Redis leases refreshed via WebSocket heartbeats.
  • Track First-Response Time (FRT): Optimize customer satisfaction by monitoring agent response latencies in real time.

Top comments (0)