DEV Community: Kseniia Shevchenko

Building a Unified Messaging Inbox: Multichannel Architecture From Scratch

Kseniia Shevchenko — Wed, 29 Apr 2026 13:27:15 +0000

Your users don't care which channel you support. They message you on WhatsApp at 9pm, email you at noon, and open a chat widget when they're frustrated at 2am. By the time they reach a human on your team, there's zero context — three separate threads, three different tools, zero shared history.

This is the multichannel inbox problem. And it's messier than it looks.

This article is about the architecture behind solving it properly — one unified inbox that aggregates WhatsApp, email, web chat, Instagram DMs, Telegram, and whatever comes next. We'll cover the data model, the real-time layer, normalization patterns, and how to avoid the failure modes that kill most implementations.

The Core Problem: N Channels × M Tools = Chaos

Most teams start like this:

WhatsApp → WhatsApp Business Manager
Email    → Gmail / Outlook  
Chat     → Intercom / Crisp
Instagram → Meta Business Suite
Telegram → some bot nobody remembers building

The result is a context-switching nightmare. Your support agent has 5 tabs open. A customer who emailed yesterday and WhatsApp'd today is treated as two different people. Nobody has the full picture.

The solution is a channel normalization layer — a single abstraction that converts every incoming message, regardless of source, into a unified format your system can reason about.

The Data Model

Start here. Everything else depends on getting this right.

-- Contacts: one record per real human
CREATE TABLE contacts (
  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  workspace_id  UUID NOT NULL REFERENCES workspaces(id),
  name          VARCHAR(255),
  email         VARCHAR(255),
  phone         VARCHAR(50),          -- E.164 format: +31612345678
  avatar_url    TEXT,
  custom_attrs  JSONB DEFAULT '{}',   -- flexible: shopify_id, plan, etc.
  created_at    TIMESTAMPTZ DEFAULT NOW(),
  updated_at    TIMESTAMPTZ DEFAULT NOW()
);

-- Channel identities: one contact, many channel identifiers
CREATE TABLE contact_identities (
  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  contact_id    UUID NOT NULL REFERENCES contacts(id) ON DELETE CASCADE,
  channel       VARCHAR(50) NOT NULL,  -- 'whatsapp' | 'email' | 'webchat' | 'instagram' | 'telegram'
  identifier    VARCHAR(255) NOT NULL, -- phone number, email, instagram user id, etc.
  metadata      JSONB DEFAULT '{}',    -- channel-specific data
  created_at    TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(channel, identifier)           -- one identity per channel
);

-- Conversations: a thread of messages
CREATE TABLE conversations (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  workspace_id    UUID NOT NULL REFERENCES workspaces(id),
  contact_id      UUID NOT NULL REFERENCES contacts(id),
  channel         VARCHAR(50) NOT NULL,
  status          VARCHAR(20) DEFAULT 'open',  -- 'open' | 'resolved' | 'snoozed'
  assignee_id     UUID REFERENCES agents(id),
  inbox_id        UUID NOT NULL REFERENCES inboxes(id),
  ai_handled      BOOLEAN DEFAULT false,
  metadata        JSONB DEFAULT '{}',
  created_at      TIMESTAMPTZ DEFAULT NOW(),
  updated_at      TIMESTAMPTZ DEFAULT NOW()
);

-- Messages: normalized across all channels
CREATE TABLE messages (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  conversation_id UUID NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
  channel         VARCHAR(50) NOT NULL,
  direction       VARCHAR(10) NOT NULL,   -- 'inbound' | 'outbound'
  sender_type     VARCHAR(10) NOT NULL,   -- 'contact' | 'agent' | 'bot'
  sender_id       UUID,
  content_type    VARCHAR(20) DEFAULT 'text',  -- 'text' | 'image' | 'audio' | 'document' | 'template'
  content         TEXT,
  attachments     JSONB DEFAULT '[]',
  external_id     VARCHAR(255),           -- channel's own message ID (for dedup)
  status          VARCHAR(20) DEFAULT 'sent', -- 'sent' | 'delivered' | 'read' | 'failed'
  created_at      TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(channel, external_id)            -- prevent duplicate processing
);

-- Inboxes: logical groupings (e.g., "WhatsApp Sales", "Email Support")
CREATE TABLE inboxes (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  workspace_id    UUID NOT NULL REFERENCES workspaces(id),
  channel         VARCHAR(50) NOT NULL,
  name            VARCHAR(255) NOT NULL,
  config          JSONB NOT NULL,         -- channel credentials, settings
  created_at      TIMESTAMPTZ DEFAULT NOW()
);

Key design decisions here:

contact_identities is separate from contacts — a single person might message you on WhatsApp AND email. Two identities, one contact record. Your identity resolution layer merges them.

external_id with UNIQUE constraint on messages — every channel gives messages their own IDs. Store them. Without this, webhook retries cause duplicate messages in your inbox.

content_type enum on messages — WhatsApp sends voice notes. Instagram sends reels. Email sends HTML. Normalize at ingestion, not at render time.

The Channel Normalization Layer

Every channel speaks a different language. Your job is to translate them all into one internal format before they touch your database.

// types/messaging.ts

interface NormalizedMessage {
  externalId: string;
  channel: Channel;
  direction: 'inbound' | 'outbound';
  contactIdentifier: string;      // phone, email, user_id — depends on channel
  contactName?: string;
  contentType: ContentType;
  content: string;
  attachments: Attachment[];
  timestamp: Date;
  rawPayload: Record<string, unknown>; // always store the original
}

type Channel = 'whatsapp' | 'email' | 'webchat' | 'instagram' | 'telegram';
type ContentType = 'text' | 'image' | 'audio' | 'video' | 'document' | 'template';

interface Attachment {
  type: ContentType;
  url: string;
  mimeType?: string;
  fileName?: string;
  size?: number;
}

Now implement a normalizer for each channel:

// normalizers/whatsapp.ts
export function normalizeWhatsAppMessage(payload: WhatsAppWebhookPayload): NormalizedMessage | null {
  const entry = payload.entry?.[0];
  const change = entry?.changes?.[0];
  const message = change?.value?.messages?.[0];

  if (!message) return null;

  const contact = change?.value?.contacts?.[0];

  return {
    externalId: message.id,
    channel: 'whatsapp',
    direction: 'inbound',
    contactIdentifier: message.from,          // E.164 phone number
    contactName: contact?.profile?.name,
    contentType: normalizeWhatsAppContentType(message.type),
    content: extractWhatsAppContent(message),
    attachments: extractWhatsAppAttachments(message),
    timestamp: new Date(parseInt(message.timestamp) * 1000),
    rawPayload: payload
  };
}

function normalizeWhatsAppContentType(type: string): ContentType {
  const map: Record<string, ContentType> = {
    text: 'text',
    image: 'image',
    audio: 'audio',
    video: 'video',
    document: 'document',
    template: 'template'
  };
  return map[type] || 'text';
}

function extractWhatsAppContent(message: any): string {
  switch (message.type) {
    case 'text': return message.text?.body || '';
    case 'image': return message.image?.caption || '[Image]';
    case 'audio': return '[Voice message]';
    case 'document': return message.document?.filename || '[Document]';
    default: return '';
  }
}

// normalizers/email.ts
import { ParsedMail } from 'mailparser';

export function normalizeEmailMessage(parsed: ParsedMail, rawEmail: string): NormalizedMessage {
  return {
    externalId: parsed.messageId || generateId(),
    channel: 'email',
    direction: 'inbound',
    contactIdentifier: parsed.from?.value[0]?.address || '',
    contactName: parsed.from?.value[0]?.name,
    contentType: 'text',
    content: parsed.text || stripHtml(parsed.html || ''),
    attachments: (parsed.attachments || []).map(att => ({
      type: 'document' as ContentType,
      url: '',                              // upload to S3 first, store URL
      mimeType: att.contentType,
      fileName: att.filename,
      size: att.size
    })),
    timestamp: parsed.date || new Date(),
    rawPayload: { headers: parsed.headers, subject: parsed.subject }
  };
}

// normalizers/telegram.ts
export function normalizeTelegramMessage(update: TelegramUpdate): NormalizedMessage | null {
  const message = update.message || update.edited_message;
  if (!message) return null;

  return {
    externalId: `${update.update_id}`,
    channel: 'telegram',
    direction: 'inbound',
    contactIdentifier: `${message.from.id}`,
    contactName: [message.from.first_name, message.from.last_name].filter(Boolean).join(' '),
    contentType: message.photo ? 'image' : message.voice ? 'audio' : 'text',
    content: message.text || message.caption || '',
    attachments: [],
    timestamp: new Date(message.date * 1000),
    rawPayload: update
  };
}

The Ingestion Pipeline

Webhook → normalize → deduplicate → resolve contact → route to conversation:

// services/MessageIngestionService.ts

export class MessageIngestionService {
  constructor(
    private db: Database,
    private contactResolver: ContactResolutionService,
    private conversationRouter: ConversationRoutingService,
    private realtimePublisher: RealtimePublisher
  ) {}

  async ingest(normalized: NormalizedMessage): Promise<void> {
    // 1. Deduplicate
    const exists = await this.db.messages.findOne({
      channel: normalized.channel,
      external_id: normalized.externalId
    });
    if (exists) {
      console.log(`Duplicate message ${normalized.externalId} — skipping`);
      return;
    }

    // 2. Resolve or create contact
    const contact = await this.contactResolver.resolve({
      channel: normalized.channel,
      identifier: normalized.contactIdentifier,
      name: normalized.contactName
    });

    // 3. Find or create conversation
    const conversation = await this.conversationRouter.route({
      contact,
      channel: normalized.channel,
      inboxId: await this.getInboxId(normalized.channel)
    });

    // 4. Persist the message
    const message = await this.db.messages.create({
      conversation_id: conversation.id,
      channel: normalized.channel,
      direction: normalized.direction,
      sender_type: 'contact',
      sender_id: contact.id,
      content_type: normalized.contentType,
      content: normalized.content,
      attachments: normalized.attachments,
      external_id: normalized.externalId,
      created_at: normalized.timestamp
    });

    // 5. Update conversation timestamp
    await this.db.conversations.update(conversation.id, {
      updated_at: new Date()
    });

    // 6. Publish to real-time layer
    await this.realtimePublisher.publish(`workspace:${conversation.workspace_id}`, {
      type: 'message.created',
      data: { message, conversation, contact }
    });

    // 7. Trigger AI or routing
    await this.conversationRouter.handleNewMessage(conversation, message, contact);
  }
}

Contact Resolution: Merging Identities

This is the hard part. The same human messages you on WhatsApp and then emails you. How do you know it's the same person?

// services/ContactResolutionService.ts

export class ContactResolutionService {
  async resolve(params: {
    channel: Channel;
    identifier: string;
    name?: string;
    email?: string;
    phone?: string;
  }): Promise<Contact> {

    // Step 1: Look up by channel identity (most reliable)
    const identity = await this.db.contactIdentities.findOne({
      channel: params.channel,
      identifier: params.identifier
    });

    if (identity) {
      return this.db.contacts.findById(identity.contact_id);
    }

    // Step 2: Try to match by email or phone across channels
    let existingContact: Contact | null = null;

    if (params.email) {
      existingContact = await this.db.contacts.findOne({ email: params.email });
    }

    if (!existingContact && params.phone) {
      existingContact = await this.db.contacts.findOne({ 
        phone: normalizePhone(params.phone) 
      });
    }

    if (existingContact) {
      // Link this channel identity to existing contact
      await this.db.contactIdentities.create({
        contact_id: existingContact.id,
        channel: params.channel,
        identifier: params.identifier
      });
      return existingContact;
    }

    // Step 3: Create new contact
    const newContact = await this.db.contacts.create({
      name: params.name,
      email: params.email,
      phone: params.phone ? normalizePhone(params.phone) : null
    });

    await this.db.contactIdentities.create({
      contact_id: newContact.id,
      channel: params.channel,
      identifier: params.identifier
    });

    return newContact;
  }
}

// Always normalize to E.164 before storing
function normalizePhone(phone: string): string {
  const digits = phone.replace(/\D/g, '');
  return digits.startsWith('+') ? phone : `+${digits}`;
}

Real-Time Layer: WebSockets for the Inbox UI

Your agents need live updates. New message arrives → UI updates instantly without polling.

// services/RealtimePublisher.ts
import { Server as SocketIOServer } from 'socket.io';
import { createAdapter } from '@socket.io/redis-adapter';
import { createClient } from 'redis';

export class RealtimePublisher {
  private io: SocketIOServer;

  constructor(httpServer: any) {
    this.io = new SocketIOServer(httpServer, {
      cors: { origin: process.env.FRONTEND_URL }
    });

    // Redis adapter for horizontal scaling
    const pubClient = createClient({ url: process.env.REDIS_URL });
    const subClient = pubClient.duplicate();

    Promise.all([pubClient.connect(), subClient.connect()]).then(() => {
      this.io.adapter(createAdapter(pubClient, subClient));
    });

    this.setupAuthMiddleware();
  }

  private setupAuthMiddleware() {
    this.io.use(async (socket, next) => {
      const token = socket.handshake.auth.token;
      const agent = await verifyAgentToken(token);
      if (!agent) return next(new Error('Unauthorized'));

      socket.data.agent = agent;
      socket.join(`workspace:${agent.workspace_id}`);
      next();
    });
  }

  async publish(room: string, event: { type: string; data: unknown }) {
    this.io.to(room).emit(event.type, event.data);
  }
}

Frontend (React) subscribes to the room:

// hooks/useRealtimeInbox.ts
import { useEffect, useCallback } from 'react';
import { io, Socket } from 'socket.io-client';
import { useInboxStore } from '../stores/inboxStore';

let socket: Socket;

export function useRealtimeInbox(token: string) {
  const { addMessage, updateConversation } = useInboxStore();

  useEffect(() => {
    socket = io(process.env.NEXT_PUBLIC_API_URL!, {
      auth: { token }
    });

    socket.on('message.created', ({ message, conversation }) => {
      addMessage(conversation.id, message);
      updateConversation(conversation);
    });

    socket.on('conversation.assigned', ({ conversation }) => {
      updateConversation(conversation);
    });

    socket.on('agent.typing', ({ conversationId, agentName }) => {
      // Show typing indicator in UI
    });

    return () => { socket.disconnect(); };
  }, [token]);

  // Send typing indicator
  const sendTyping = useCallback((conversationId: string) => {
    socket.emit('typing', { conversationId });
  }, []);

  return { sendTyping };
}

Sending Replies: The Outbound Layer

The outbound side is simpler — you pick the right channel adapter and fire:

// services/OutboundMessageService.ts

interface SendMessageParams {
  conversationId: string;
  content: string;
  contentType?: ContentType;
  agentId: string;
}

export class OutboundMessageService {
  private adapters: Map<Channel, ChannelAdapter>;

  constructor() {
    this.adapters = new Map([
      ['whatsapp', new WhatsAppAdapter()],
      ['email',    new EmailAdapter()],
      ['telegram', new TelegramAdapter()],
      ['webchat',  new WebChatAdapter()],
    ]);
  }

  async send(params: SendMessageParams): Promise<void> {
    const conversation = await this.db.conversations.findById(params.conversationId);
    const contact = await this.db.contacts.findById(conversation.contact_id);
    const identity = await this.db.contactIdentities.findOne({
      contact_id: contact.id,
      channel: conversation.channel
    });

    const adapter = this.adapters.get(conversation.channel as Channel);
    if (!adapter) throw new Error(`No adapter for channel: ${conversation.channel}`);

    // Send via channel
    const externalId = await adapter.send({
      identifier: identity.identifier,
      content: params.content,
      contentType: params.contentType || 'text'
    });

    // Persist outbound message
    const message = await this.db.messages.create({
      conversation_id: params.conversationId,
      channel: conversation.channel,
      direction: 'outbound',
      sender_type: 'agent',
      sender_id: params.agentId,
      content_type: params.contentType || 'text',
      content: params.content,
      external_id: externalId,
      status: 'sent'
    });

    // Publish to real-time
    await this.realtimePublisher.publish(`workspace:${conversation.workspace_id}`, {
      type: 'message.created',
      data: { message, conversation }
    });
  }
}

Channel adapter example for WhatsApp:

// adapters/WhatsAppAdapter.ts

export class WhatsAppAdapter implements ChannelAdapter {
  private baseUrl = 'https://graph.facebook.com/v19.0';

  async send(params: {
    identifier: string;  // E.164 phone
    content: string;
    contentType: ContentType;
  }): Promise<string> {
    const response = await fetch(
      `${this.baseUrl}/${process.env.WHATSAPP_PHONE_NUMBER_ID}/messages`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.WHATSAPP_ACCESS_TOKEN}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          messaging_product: 'whatsapp',
          recipient_type: 'individual',
          to: params.identifier,
          type: 'text',
          text: { body: params.content }
        })
      }
    );

    const data = await response.json();

    if (!response.ok) {
      throw new Error(`WhatsApp send failed: ${JSON.stringify(data.error)}`);
    }

    return data.messages[0].id; // external message ID
  }

  async handleDeliveryUpdate(payload: any): Promise<void> {
    const status = payload.entry?.[0]?.changes?.[0]?.value?.statuses?.[0];
    if (!status) return;

    // Update message delivery status
    await this.db.messages.update(
      { channel: 'whatsapp', external_id: status.id },
      { status: status.status }  // 'delivered' | 'read' | 'failed'
    );
  }
}

Webhook Router: One Endpoint, Many Channels

Don't create a separate route for each channel. One router, channel-specific handlers:

// routes/webhooks.ts

router.post('/channels/:channel', async (req, res) => {
  const { channel } = req.params;

  // Always acknowledge fast
  res.status(200).json({ status: 'received' });

  try {
    await webhookQueue.add('process', {
      channel,
      payload: req.body,
      headers: req.headers
    });
  } catch (error) {
    console.error('Failed to queue webhook:', error);
  }
});

// Worker
const worker = new Worker('webhooks', async (job) => {
  const { channel, payload, headers } = job.data;

  // Verify signature per channel
  await verifyChannelSignature(channel, payload, headers);

  // Normalize
  const normalizer = normalizers[channel];
  const normalized = normalizer(payload);

  if (!normalized) return; // status updates, read receipts, etc.

  // Ingest
  await ingestionService.ingest(normalized);
}, { connection, concurrency: 20 });

The Failure Modes to Avoid

1. Processing webhooks synchronously
Channels expect a 200 response in under 5 seconds. If your processing takes 6 seconds — WhatsApp retries. You get duplicates. Always queue, always acknowledge fast.

2. Not storing external_id
Every channel retries failed webhooks. Without deduplication on external_id, your agents see the same message 3 times. Add the UNIQUE constraint on day one.

3. Separate contact records per channel
If WhatsApp contact and email contact are stored separately, your agents have zero cross-channel context. The contact_identities pattern solves this — invest in the identity resolution logic early.

4. Polling instead of WebSockets
Polling every 2 seconds for new messages means 30 requests/minute per agent. With 10 agents: 300 requests/minute, all returning empty responses. WebSockets + Redis pub/sub scales to thousands of concurrent agents at a fraction of the cost.

5. Hardcoding channel logic in the inbox UI
If your frontend has if (channel === 'whatsapp') { ... } scattered everywhere, adding Instagram breaks 12 components. Normalize at the API layer. Your UI should only know about Message, never about WhatsAppMessage.

What This Looks Like in Production

Incoming WhatsApp message
         │
         ▼
POST /webhooks/whatsapp
         │
    (200 immediately)
         │
         ▼
    BullMQ Queue
         │
         ▼
   Verify HMAC signature
         │
         ▼
   Normalize to NormalizedMessage
         │
         ▼
   Deduplicate (check external_id)
         │
         ▼
   Resolve Contact
   (existing? merge identity. new? create.)
         │
         ▼
   Route to Conversation
   (open thread? append. new? create.)
         │
         ▼
   Persist Message to PostgreSQL
         │
         ▼
   Publish to Redis → Socket.IO
         │
         ▼
   Agent inbox updates in real-time
         │
         ▼
   AI Bot evaluates → responds or escalates

Total latency from WhatsApp send to agent inbox update: under 800ms on a decent server.

Tools & Libraries Used

{
  "dependencies": {
    "socket.io": "^4.7.0",
    "@socket.io/redis-adapter": "^8.3.0",
    "bullmq": "^5.0.0",
    "ioredis": "^5.3.0",
    "mailparser": "^3.6.0",
    "bottleneck": "^2.19.5"
  }
}

If you don't want to build this from scratch, Oscar Chat implements this architecture out of the box — WhatsApp, Telegram, email, and web chat all in one inbox, with an AI layer on top. Worth looking at before you commit to building the entire normalization layer yourself.

Building an AI-Powered Customer Support Layer with Oscar Chat API: A Developer's Guide

Kseniia Shevchenko — Wed, 29 Apr 2026 13:24:01 +0000

If you're a founder who writes code, you've probably built your product's support flow wrong at least once. I know I did — a patchwork of Intercom webhooks, a custom Node.js handler, a Slack bot that never quite worked, and three different inboxes nobody checked consistently.

This guide is the thing I wish existed when I started. We'll build a proper AI-first customer support system using the Oscar Chat API, cover the architecture decisions that matter, and look at real integration patterns for Shopify, webhooks, and custom automation flows.

The Architecture Before We Write a Single Line

Before touching the API, understand the mental model. Oscar Chat exposes four core primitives:

┌─────────────────────────────────────────────────────┐
│                   Oscar Chat API                     │
│                                                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │
│  │ Widgets  │  │  Inbox   │  │   AI Bot Engine  │  │
│  │  (embed) │  │ (unified)│  │  (GPT-4o / etc.) │  │
│  └────┬─────┘  └────┬─────┘  └────────┬─────────┘  │
│       │              │                  │             │
│  ┌────▼──────────────▼──────────────────▼──────────┐│
│  │              REST API + Webhooks                 ││
│  └──────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
         │                    │
   Your frontend         Your backend
   (widget.js)          (webhook handler,
                         CRM sync, Slack alerts)

Widgets — the front-facing chat/popup components embedded on your site.

Inbox — unified conversation store across all channels (web chat, WhatsApp, email).

AI Bot Engine — the layer that handles first-response automation, trained on your content.

REST API + Webhooks — how you connect all of this to your stack.

The pattern we'll build:

Widget captures visitor intent
AI bot handles first response (trained on your docs)
Webhook fires when human escalation is needed
Your backend routes to Slack / CRM / email
Agent responds from unified inbox

Step 1: Authentication

Oscar Chat uses Bearer token auth. Get your API key from the dashboard under Settings → API.

// config/oscarchat.js
const OSCAR_API_BASE = 'https://api.oscarchat.ai/v1';
const OSCAR_API_KEY = process.env.OSCAR_API_KEY; // never hardcode this

const oscarClient = {
  headers: {
    'Authorization': `Bearer ${OSCAR_API_KEY}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  baseUrl: OSCAR_API_BASE
};

module.exports = oscarClient;

Test your connection:

curl -X GET https://api.oscarchat.ai/v1/workspaces \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Expected response:

{
  "data": [
    {
      "id": "ws_01H8X...",
      "name": "My Store",
      "created_at": "2026-01-15T10:00:00Z",
      "plan": "pro"
    }
  ]
}

Step 2: Embed the Widget (the Right Way)

The basic embed is one script tag. But for production, you want async loading with proper initialization:

<!-- Load async, don't block render -->
<script>
  (function(w, d, s, o) {
    var js = d.createElement(s);
    js.id = o;
    js.async = true;
    js.src = 'https://widget.oscarchat.ai/loader.js';
    js.setAttribute('data-widget-id', 'YOUR_WIDGET_ID');
    d.head.appendChild(js);

    // Queue commands before widget loads
    w[o] = w[o] || function() {
      (w[o].q = w[o].q || []).push(arguments);
    };
  })(window, document, 'script', 'OscarChat');
</script>

Passing User Context

If your user is authenticated, pass their data to Oscar Chat so your agents have context:

// After user logs in
OscarChat('identify', {
  user_id: user.id,           // your internal ID
  email: user.email,
  name: user.name,
  plan: user.subscription,    // custom attributes
  shopify_store: user.store_url,
  total_orders: user.orderCount,
  created_at: user.joinedAt
});

This populates the agent's sidebar with real customer data — no more tab-switching to your CRM during conversations.

Triggering the Chat Programmatically

Don't rely only on the bubble. Open the chat based on user behavior:

// Open chat when user clicks a custom button
document.getElementById('help-btn').addEventListener('click', () => {
  OscarChat('open');
});

// Pre-fill a message
OscarChat('open', {
  message: 'I need help with my order #' + orderId
});

// Show a specific bot flow
OscarChat('startFlow', {
  flow_id: 'return_request',
  context: { order_id: orderId }
});

Step 3: Webhooks — the Real Power

This is where it gets interesting. Webhooks let your backend react to conversation events in real time.

Register a Webhook Endpoint

curl -X POST https://api.oscarchat.ai/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/oscarchat",
    "events": [
      "conversation.created",
      "conversation.assigned",
      "message.created",
      "conversation.resolved",
      "bot.escalated"
    ],
    "secret": "your_webhook_signing_secret"
  }'

Response:

{
  "id": "wh_01H9K...",
  "url": "https://yourapp.com/webhooks/oscarchat",
  "events": ["conversation.created", "message.created", "bot.escalated"],
  "secret": "your_webhook_signing_secret",
  "created_at": "2026-04-29T10:00:00Z"
}

Build the Webhook Handler

// routes/webhooks.js (Express)
const express = require('express');
const crypto = require('crypto');
const router = express.Router();

// Verify signature — ALWAYS do this
function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const computed = 'sha256=' + hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(signature)
  );
}

router.post('/oscarchat', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.headers['x-oscar-signature'];
  const payload = req.body;

  // Reject unverified requests
  if (!verifySignature(payload, signature, process.env.OSCAR_WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Acknowledge immediately — process async
  res.status(200).json({ received: true });

  const event = JSON.parse(payload);
  await processWebhookEvent(event);
});

async function processWebhookEvent(event) {
  switch (event.type) {
    case 'bot.escalated':
      await handleBotEscalation(event.data);
      break;
    case 'conversation.created':
      await handleNewConversation(event.data);
      break;
    case 'message.created':
      await handleNewMessage(event.data);
      break;
    case 'conversation.resolved':
      await handleResolved(event.data);
      break;
    default:
      console.log('Unhandled event type:', event.type);
  }
}

module.exports = router;

Handle Bot Escalation (Most Important)

When the AI can't answer, you want to know immediately:

async function handleBotEscalation(data) {
  const { conversation_id, contact, last_message, reason } = data;

  // 1. Notify team on Slack
  await notifySlack({
    channel: '#support-urgent',
    text: `🚨 Bot escalation needed`,
    blocks: [
      {
        type: 'section',
        text: {
          type: 'mrkdwn',
          text: `*Customer:* ${contact.name} (${contact.email})\n*Reason:* ${reason}\n*Last message:* "${last_message}"`
        }
      },
      {
        type: 'actions',
        elements: [{
          type: 'button',
          text: { type: 'plain_text', text: 'Open Conversation' },
          url: `https://app.oscarchat.ai/conversations/${conversation_id}`,
          style: 'primary'
        }]
      }
    ]
  });

  // 2. Assign to available agent via API
  const agent = await getAvailableAgent();
  if (agent) {
    await assignConversation(conversation_id, agent.id);
  }

  // 3. Log to your CRM
  await updateCRMContact(contact.email, {
    last_support_escalation: new Date().toISOString(),
    escalation_reason: reason
  });
}

Step 4: Conversations API — Read and Write

Pull conversation data into your own systems:

// Get all open conversations
async function getOpenConversations(workspaceId) {
  const response = await fetch(
    `https://api.oscarchat.ai/v1/workspaces/${workspaceId}/conversations?status=open&limit=50`,
    { headers: oscarClient.headers }
  );
  return response.json();
}

// Get a specific conversation with full history
async function getConversation(conversationId) {
  const response = await fetch(
    `https://api.oscarchat.ai/v1/conversations/${conversationId}?include=messages,contact,assignee`,
    { headers: oscarClient.headers }
  );
  return response.json();
}

// Send a message as a bot/agent
async function sendMessage(conversationId, content, type = 'outgoing') {
  const response = await fetch(
    `https://api.oscarchat.ai/v1/conversations/${conversationId}/messages`,
    {
      method: 'POST',
      headers: oscarClient.headers,
      body: JSON.stringify({
        content,
        message_type: type,       // 'outgoing' = agent, 'activity' = system note
        content_type: 'text',     // 'text' | 'markdown' | 'html'
        private: false            // true = internal note, not visible to customer
      })
    }
  );
  return response.json();
}

// Assign conversation to agent
async function assignConversation(conversationId, agentId) {
  const response = await fetch(
    `https://api.oscarchat.ai/v1/conversations/${conversationId}/assignments`,
    {
      method: 'POST',
      headers: oscarClient.headers,
      body: JSON.stringify({ assignee_id: agentId })
    }
  );
  return response.json();
}

Step 5: Shopify Integration Pattern

This is the most common use case — sync Oscar Chat with your Shopify store so agents see order data inline.

// server/integrations/shopify-oscar.js
const Shopify = require('@shopify/shopify-api');

// When a conversation starts, enrich with Shopify data
async function enrichConversationWithShopifyData(event) {
  const { conversation_id, contact } = event.data;

  if (!contact.email) return;

  try {
    // Find customer in Shopify
    const customers = await shopify.rest.Customer.all({
      session,
      email: contact.email
    });

    if (!customers.data.length) return;

    const customer = customers.data[0];

    // Get their recent orders
    const orders = await shopify.rest.Order.all({
      session,
      customer_id: customer.id,
      limit: 5,
      status: 'any'
    });

    // Add as internal note to the conversation
    const orderSummary = orders.data.map(o => 
      `#${o.order_number} — ${o.financial_status} — $${o.total_price} (${o.created_at.split('T')[0]})`
    ).join('\n');

    await sendMessage(conversation_id, 
      `📦 Shopify Customer Data:\n` +
      `Total orders: ${customer.orders_count}\n` +
      `Total spent: $${customer.total_spent}\n` +
      `Recent orders:\n${orderSummary}`,
      'activity'  // internal note, agent sees but customer doesn't
    );

    // Also update the contact's custom attributes
    await updateContact(contact.id, {
      shopify_customer_id: customer.id,
      total_orders: customer.orders_count,
      total_spent: customer.total_spent,
      shopify_tags: customer.tags
    });

  } catch (error) {
    console.error('Shopify enrichment failed:', error);
  }
}

async function updateContact(contactId, attributes) {
  return fetch(`https://api.oscarchat.ai/v1/contacts/${contactId}`, {
    method: 'PATCH',
    headers: oscarClient.headers,
    body: JSON.stringify({ custom_attributes: attributes })
  });
}

Step 6: AI Bot Configuration via API

You don't have to use the UI to configure your bot. The API lets you update bot behavior programmatically:

// Update bot knowledge base with new content
async function addKnowledgeSource(botId, source) {
  const response = await fetch(
    `https://api.oscarchat.ai/v1/bots/${botId}/knowledge_sources`,
    {
      method: 'POST',
      headers: oscarClient.headers,
      body: JSON.stringify({
        type: source.type,      // 'url' | 'document' | 'text'
        url: source.url,        // for type: 'url'
        content: source.content, // for type: 'text'
        name: source.name
      })
    }
  );
  return response.json();
}

// Trigger re-training when your docs update
async function syncDocsToBot(botId) {
  const pages = [
    'https://yourapp.com/docs/getting-started',
    'https://yourapp.com/docs/api-reference',
    'https://yourapp.com/pricing',
    'https://yourapp.com/faq'
  ];

  for (const url of pages) {
    await addKnowledgeSource(botId, {
      type: 'url',
      url,
      name: url.split('/').pop()
    });
  }

  // Trigger sync
  await fetch(`https://api.oscarchat.ai/v1/bots/${botId}/sync`, {
    method: 'POST',
    headers: oscarClient.headers
  });

  console.log('Bot knowledge base updated');
}

// Call this in your CI/CD pipeline after docs deploy
// e.g., in your GitHub Actions workflow:
// - name: Sync docs to Oscar Chat bot
//   run: node scripts/sync-bot-docs.js

Step 7: Custom Escalation Logic

The default AI escalation is good, but you can build smarter rules:

// Intercept messages before the bot responds
// Use this for custom routing logic

async function smartEscalationRouter(event) {
  const { conversation_id, message, contact } = event.data;
  const content = message.content.toLowerCase();

  // High-priority keywords → skip bot, go straight to human
  const urgentKeywords = ['refund', 'fraud', 'hack', 'lawsuit', 'cancel subscription', 'charge'];
  const isUrgent = urgentKeywords.some(kw => content.includes(kw));

  if (isUrgent) {
    // Immediately assign to senior support agent
    const seniorAgent = await getSeniorAgent();
    await assignConversation(conversation_id, seniorAgent.id);

    // Add high-priority label
    await addLabel(conversation_id, 'urgent');

    // Send to priority Slack channel
    await notifySlack({ channel: '#support-priority', data: event.data });
    return;
  }

  // VIP customers → always get a human
  const isVIP = contact.custom_attributes?.plan === 'enterprise' || 
                parseFloat(contact.custom_attributes?.total_spent) > 1000;

  if (isVIP) {
    const agent = await getAvailableAgent();
    await assignConversation(conversation_id, agent.id);
    await addLabel(conversation_id, 'vip');
    return;
  }

  // Everything else → let the AI handle it
  // Bot responds automatically, no action needed
}

async function addLabel(conversationId, label) {
  return fetch(`https://api.oscarchat.ai/v1/conversations/${conversationId}/labels`, {
    method: 'POST',
    headers: oscarClient.headers,
    body: JSON.stringify({ labels: [label] })
  });
}

Step 8: Analytics and Reporting

Pull support metrics into your own dashboard:

// Get conversation stats for a date range
async function getSupportMetrics(workspaceId, startDate, endDate) {
  const response = await fetch(
    `https://api.oscarchat.ai/v1/workspaces/${workspaceId}/reports/summary?` +
    `since=${startDate}&until=${endDate}&type=account`,
    { headers: oscarClient.headers }
  );

  const data = await response.json();

  return {
    totalConversations: data.conversations_count,
    avgFirstResponseTime: data.avg_first_response_time,    // seconds
    avgResolutionTime: data.avg_resolution_time,            // seconds
    botResolutionRate: data.bot_resolution_rate,            // percentage
    csat: data.csat_survey_score                            // 0-5
  };
}

// Example: weekly Slack report
async function sendWeeklyReport() {
  const endDate = Math.floor(Date.now() / 1000);
  const startDate = endDate - (7 * 24 * 60 * 60);

  const metrics = await getSupportMetrics('YOUR_WORKSPACE_ID', startDate, endDate);

  const botRate = (metrics.botResolutionRate * 100).toFixed(1);
  const avgResponseMins = (metrics.avgFirstResponseTime / 60).toFixed(1);

  await notifySlack({
    channel: '#support-metrics',
    text: `📊 Weekly Support Report`,
    blocks: [{
      type: 'section',
      fields: [
        { type: 'mrkdwn', text: `*Total Conversations*\n${metrics.totalConversations}` },
        { type: 'mrkdwn', text: `*Bot Resolution Rate*\n${botRate}%` },
        { type: 'mrkdwn', text: `*Avg First Response*\n${avgResponseMins} min` },
        { type: 'mrkdwn', text: `*CSAT Score*\n${metrics.csat}/5` }
      ]
    }]
  });
}

// Schedule with node-cron
const cron = require('node-cron');
cron.schedule('0 9 * * 1', sendWeeklyReport); // Every Monday at 9am

Production Checklist

Before you ship this to production:

Infrastructure
├── [ ] API key in environment variables (never in code)
├── [ ] Webhook signing secret verified on every request
├── [ ] Webhook handler returns 200 immediately, processes async
├── [ ] Retry logic for failed API calls (exponential backoff)
└── [ ] Rate limit handling (Oscar Chat API: 300 req/min)

Reliability
├── [ ] Queue webhook events (Redis/BullMQ) — don't process inline
├── [ ] Idempotency checks (same event can arrive twice)
├── [ ] Dead letter queue for failed webhook processing
└── [ ] Monitoring on webhook endpoint (PagerDuty / Sentry)

Testing
├── [ ] Local webhook testing with ngrok or Cloudflare Tunnel
├── [ ] Test each event type with mock payloads
└── [ ] Load test your webhook handler before traffic spikes

Rate Limiting Pattern

// Simple rate limiter for Oscar Chat API
const Bottleneck = require('bottleneck');

const limiter = new Bottleneck({
  minTime: 200,        // 5 requests per second max
  maxConcurrent: 10,
  reservoir: 300,      // 300 requests
  reservoirRefreshAmount: 300,
  reservoirRefreshInterval: 60 * 1000  // per minute
});

// Wrap all API calls
const fetchWithRateLimit = limiter.wrap(fetch);

Webhook Queue Pattern

// Use BullMQ to process webhooks reliably
const { Queue, Worker } = require('bullmq');
const IORedis = require('ioredis');

const connection = new IORedis(process.env.REDIS_URL);
const webhookQueue = new Queue('oscar-webhooks', { connection });

// In your webhook endpoint — just enqueue, return fast
router.post('/oscarchat', async (req, res) => {
  // verify signature first...

  await webhookQueue.add('process', JSON.parse(req.body), {
    attempts: 3,
    backoff: { type: 'exponential', delay: 2000 }
  });

  res.status(200).json({ received: true });
});

// Separate worker process
const worker = new Worker('oscar-webhooks', async (job) => {
  await processWebhookEvent(job.data);
}, { connection });

worker.on('failed', (job, err) => {
  console.error(`Webhook job ${job.id} failed:`, err);
  // Alert your team
});

Putting It All Together

Here's the complete data flow in production:

Visitor lands on your site
       │
       ▼
Oscar Chat widget loads (async)
       │
       ▼
User identified → context passed via OscarChat('identify', {...})
       │
       ▼
User sends message
       │
       ▼
AI Bot evaluates:
  ├── Known question → AI answers instantly
  └── Unknown / urgent / VIP → escalates
             │
             ▼
         Webhook fires → your backend
             │
        ┌────┴─────────────────────┐
        │                          │
        ▼                          ▼
  Slack notification          CRM updated
  with conversation link      (Shopify data enriched)
        │
        ▼
  Agent picks up from
  unified inbox with full context

That's the system. No tab-switching, no "let me look that up", no 4-hour response times. Your AI handles 70-80% of conversations. The rest go to humans who have all the context they need before they type the first word.