@hexabot-ai/api 3.1.3-alpha.0 → 3.2.0-alpha.0

package/src/extensions/channels/web/base-web-channel.ts

@@ -4,6 +4,17 @@
  * Full terms: see LICENSE.md.
  */
 
+import type {
+  Attachment,
+  Source,
+  StdOutgoingMessageEnvelope,
+  Subscriber,
+} from '@hexabot-ai/types';
+import {
+  ActionOptions,
+  OutgoingMessageType,
+  StdEventType,
+} from '@hexabot-ai/types';
 import {
   HttpException,
   HttpStatus,
@@ -15,157 +26,197 @@ import { OnEvent } from '@nestjs/event-emitter';
 import { Request, Response } from 'express';
 import { Socket } from 'socket.io';
 import { v4 as uuidv4 } from 'uuid';
+import type { z } from 'zod';
 
-import { Attachment } from '@/attachment/dto/attachment.dto';
 import { AttachmentOrmEntity } from '@/attachment/entities/attachment.entity';
 import {
   AttachmentAccess,
   AttachmentCreatedByRef,
   AttachmentResourceRef,
 } from '@/attachment/types';
-import ChannelHandler from '@/channel/lib/Handler';
-import { MessageInboundEvent } from '@/channel/lib/inbound-events';
 import {
-  inferOutgoingMessageEnvelope,
-  UnsupportedOutgoingFormatError,
-} from '@/channel/lib/outbound';
-import { ChannelAttachmentService } from '@/channel/services/channel-attachment.service';
+  ChannelCapabilities,
+  DEFAULT_CHANNEL_CAPABILITIES,
+  ExtensionInject,
+  WebSocketChannelHandler,
+} from '@/channel';
+import { MessageInboundEvent } from '@/channel/lib/inbound-events';
+import { SourceService } from '@/channel/services/source.service';
 import { ChannelName } from '@/channel/types';
+import { SubscriberChannelData } from '@/chat';
 import { MessageCreateDto } from '@/chat/dto/message.dto';
-import { Subscriber, SubscriberCreateDto } from '@/chat/dto/subscriber.dto';
-import { Thread } from '@/chat/dto/thread.dto';
+import { SubscriberCreateDto } from '@/chat/dto/subscriber.dto';
 import { MessageService } from '@/chat/services/message.service';
-import { SubscriberService } from '@/chat/services/subscriber.service';
-import { ThreadService } from '@/chat/services/thread.service';
-import { PayloadType } from '@/chat/types/button';
-import {
-  AnyMessage,
-  IncomingMessage,
-  OutgoingMessage,
-  OutgoingMessageFormat,
-  StdEventType,
-  StdOutgoingEnvelope,
-  StdOutgoingMessage,
-} from '@/chat/types/message';
-import { ActionOptions } from '@/chat/types/options';
 import { MenuService } from '@/cms/services/menu.service';
 import { config } from '@/config';
 import { SocketRequest } from '@/websocket/utils/socket-request';
 import { SocketResponse } from '@/websocket/utils/socket-response';
-import { WebsocketGateway } from '@/websocket/websocket.gateway';
 
 import {
   AttachmentMessageInboundEvent,
   BaseWebInboundEvent,
   createWebInboundEventDecoder,
+  createWebInboundMessageEncoder,
   WebInboundEventDecoder,
+  WebInboundMessageEncoder,
   WebMessageInboundEvent,
 } from './inbound';
 import {
   createWebOutboundMessageEncoder,
   WebOutboundMessageEncoder,
 } from './outbound';
+import {
+  WebFormatContext,
+  WebHistoryService,
+} from './services/web-history.service';
+import { WebSessionService } from './services/web-session.service';
+import { WEB_CHANNEL_NAME } from './settings.schema';
 import { Web } from './types';
-import { WEB_CHANNEL_NAME } from './web-channel.settings';
 
+/**
+ * Base handler for the Socket.IO-backed "web" channel.
+ *
+ * Responsibilities:
+ * - resolves per-channel helpers via `@ExtensionInject()` (encoder/decoder, session, history)
+ * - enforces web-channel CORS rules for the HTTP socket transport endpoints
+ * - manages web session bootstrap and thread resolution
+ * - decodes inbound web events and broadcasts outbound messages over Socket.IO
+ */
 @Injectable()
 export default abstract class BaseWebChannelHandler<N extends ChannelName>
-  extends ChannelHandler<N>
+  extends WebSocketChannelHandler<N>
   implements OnModuleInit
 {
-  @Inject(SubscriberService)
-  protected readonly subscriberService: SubscriberService;
+  @Inject(MenuService)
+  private readonly menuService: MenuService;
 
   @Inject(MessageService)
-  protected readonly messageService: MessageService;
+  private readonly messageService: MessageService;
 
-  @Inject(MenuService)
-  protected readonly menuService: MenuService;
+  @Inject(SourceService)
+  private readonly sourceService: SourceService;
 
-  @Inject(WebsocketGateway)
-  protected readonly websocketGateway: WebsocketGateway;
+  @ExtensionInject((name) => createWebOutboundMessageEncoder(name))
+  private outboundMessageEncoder!: WebOutboundMessageEncoder;
 
-  @Inject(ThreadService)
-  protected readonly threadService: ThreadService;
+  @ExtensionInject((name) => createWebInboundMessageEncoder(name))
+  private inboundMessageEncoder!: WebInboundMessageEncoder;
 
-  @Inject(ChannelAttachmentService)
-  protected readonly channelAttachmentService: ChannelAttachmentService;
+  @ExtensionInject((name) => createWebInboundEventDecoder(name))
+  private inboundEventDecoder!: WebInboundEventDecoder<N>;
 
-  private outboundMessageEncoder!: WebOutboundMessageEncoder;
+  @ExtensionInject(WebSessionService)
+  private sessionService!: WebSessionService;
 
-  private inboundEventDecoder!: WebInboundEventDecoder<N>;
+  @ExtensionInject(WebHistoryService)
+  private historyService!: WebHistoryService;
 
-  constructor(name: N) {
-    super(name);
+  constructor(name: N, sourceSettingsSchema?: z.ZodTypeAny) {
+    super(name, sourceSettingsSchema);
   }
 
   async onModuleInit() {
     await super.onModuleInit();
-    const OutboundMessageEncoderProvider = createWebOutboundMessageEncoder(
-      this.getName(),
-    );
-    const InboundEventDecoderProvider = createWebInboundEventDecoder(
-      this.getName(),
-    );
-    [this.outboundMessageEncoder, this.inboundEventDecoder] = await Promise.all(
-      [
-        this.createModuleRef(OutboundMessageEncoderProvider),
-        this.createModuleRef(InboundEventDecoderProvider) as Promise<
-          WebInboundEventDecoder<N>
-        >,
-      ],
-    );
     this.logger.debug('initialization ...');
   }
 
-  /**
-   * Verify web websocket connection and return settings
-   *
-   * @param client - The socket client
-   */
+  getCapabilities(): ChannelCapabilities {
+    return { ...DEFAULT_CHANNEL_CAPABILITIES, typingIndicator: true };
+  }
+
+  generateId(): string {
+    return `${this.name}-${uuidv4()}`;
+  }
+
+  getChannelAttributes(
+    req: SocketRequest,
+  ): SubscriberChannelDict[typeof WEB_CHANNEL_NAME] {
+    return {
+      isSocket: true,
+      ipAddress: this.getIpAddress(req),
+      agent: req.headers['user-agent'] || 'browser',
+    };
+  }
+
+  private formatCtx(sourceId: string): WebFormatContext {
+    return {
+      inboundEncoder: this.inboundMessageEncoder,
+      outboundEncoder: this.outboundMessageEncoder,
+      generateId: () => this.generateId(),
+      sourceId,
+    };
+  }
+
+  private getSourceIdFromHandshake(client: Socket): string | null {
+    const rawSourceId = client.handshake.query.source_id;
+    const sourceId = Array.isArray(rawSourceId) ? rawSourceId[0] : rawSourceId;
+
+    if (typeof sourceId !== 'string') {
+      return null;
+    }
+
+    const normalizedSourceId = sourceId.trim();
+
+    return normalizedSourceId.length > 0 ? normalizedSourceId : null;
+  }
+
   @OnEvent('hook:websocket:connection', { async: true })
   async onWebSocketConnection(client: Socket) {
     try {
-      const handshake = client.handshake;
-      const { channel } = handshake.query;
+      const sourceId = this.getSourceIdFromHandshake(client);
+
+      if (!sourceId) {
+        if (client.request.session.passport?.user?.id) {
+          // Core websocket connection for system notifications (not the web/console channel one)
+          return;
+        }
+
+        this.logger.warn('Missing source_id in websocket handshake');
+        client.disconnect();
+
+        return;
+      }
+
+      const source = await this.sourceService.findActiveById(sourceId);
       const profile = client.request.session.web?.profile;
 
-      if (channel !== this.getName()) {
+      if (source.channel !== this.getName()) {
         return;
       }
 
+      client.request.session.web = {
+        ...client.request.session.web,
+        sourceId,
+      };
+
       let messages: Web.Message[] | undefined;
       let threadId: string | undefined;
 
       if (profile?.foreignId) {
         await client.join(profile.foreignId);
-        const thread = await this.threadService.resolveThread({
-          subscriberId: profile.id,
-          explicitThreadId: client.request.session.web?.threadId,
-        });
+        const thread = await this.sessionService.resolveThread(
+          profile.id,
+          client.request.session.web?.threadId,
+        );
         threadId = thread?.id;
-        const currentWebSession = client.request.session.web;
         client.request.session.web = {
-          profile: currentWebSession?.profile,
+          profile: client.request.session.web?.profile,
           threadId,
+          sourceId,
         };
-        if (thread) {
-          const messagesHistory =
-            await this.messageService.findHistoryUntilDate(thread);
-          messages = await this.formatMessages(
-            messagesHistory.reverse() as AnyMessage[],
-          );
-        } else {
-          messages = [];
-        }
+        messages = thread
+          ? await this.historyService.fetchHistory(
+              thread,
+              this.formatCtx(source.id),
+            )
+          : [];
       }
 
       this.logger.debug('WS connected .. sending settings');
-      const settings = await this.getSettings();
+      const settings = source.settings;
 
       try {
         const menu = await this.menuService.getTree();
-
         client.emit('settings', {
           menu,
           profile,
@@ -199,202 +250,19 @@ export default abstract class BaseWebChannelHandler<N extends ChannelName>
           }
     ) as SocketResponse;
     const subscriber = socket.request.session.web?.profile;
+    const sourceId = this.getSourceIdFromHandshake(socket);
 
-    if (socket.handshake.query.channel !== this.getName() || !subscriber) {
+    if (
+      !sourceId ||
+      socket.request.session.web?.sourceId !== sourceId ||
+      !subscriber
+    ) {
       return;
     }
 
     this.broadcast(subscriber, StdEventType.error, response, [socket.id]);
   }
 
-  /**
-   * Adapt incoming message structure for web channel
-   *
-   * @param incoming - Incoming message
-   * @returns Formatted web message
-   */
-  private async formatIncomingHistoryMessage(
-    incoming: IncomingMessage,
-  ): Promise<Web.InboundMessageBase> {
-    // Format incoming message
-    if ('type' in incoming.message) {
-      if (incoming.message.type === PayloadType.location) {
-        const coordinates = incoming.message.coordinates;
-
-        return {
-          type: Web.InboundMessageType.location,
-          data: {
-            coordinates: {
-              lat: coordinates.lat,
-              lng: coordinates.lon,
-            },
-          },
-        };
-      } else {
-        // @TODO : handle multiple files
-        const attachmentPayload = Array.isArray(incoming.message.attachment)
-          ? incoming.message.attachment[0]
-          : incoming.message.attachment;
-
-        return {
-          type: Web.InboundMessageType.file,
-          data: {
-            type: attachmentPayload.type,
-            url: await this.channelAttachmentService.getPublicUrl(
-              this.getName(),
-              attachmentPayload.payload,
-            ),
-          },
-        };
-      }
-    } else {
-      return {
-        type: Web.InboundMessageType.text,
-        data: incoming.message,
-      };
-    }
-  }
-
-  /**
-   * Adapt the outgoing message structure for web channel
-   *
-   * @param outgoing - The outgoing message
-   * @returns Formatted web message
-   */
-  private async formatOutgoingHistoryMessage(
-    outgoing: OutgoingMessage,
-  ): Promise<Web.OutboundMessageBase> {
-    const envelope = inferOutgoingMessageEnvelope(outgoing.message);
-    const options: ActionOptions =
-      'options' in outgoing.message
-        ? {
-            content: outgoing.message.options,
-          }
-        : {};
-
-    return await this.outboundMessageEncoder.encode(envelope, options);
-  }
-
-  /**
-   * Checks if a given message is an IncomingMessage
-   *
-   * @param message Any type of message
-   * @returns True, if it's a incoming message
-   */
-  private isIncomingMessage(message: AnyMessage): message is IncomingMessage {
-    return 'sender' in message && !!message.sender;
-  }
-
-  /**
-   * Adapt the message structure for web channel
-   *
-   * @param messages - The messages to be formatted
-   *
-   * @returns Formatted message
-   */
-  protected async formatMessages(
-    messages: AnyMessage[],
-  ): Promise<Web.Message[]> {
-    const formattedMessages: Web.Message[] = [];
-
-    for (const anyMessage of messages) {
-      const messageMid = anyMessage.mid ?? this.generateId();
-      if (this.isIncomingMessage(anyMessage)) {
-        const message = await this.formatIncomingHistoryMessage(anyMessage);
-        formattedMessages.push({
-          ...message,
-          author: anyMessage.sender,
-          read: true, // Temporary fix as read is false in the bd
-          mid: messageMid,
-          createdAt: anyMessage.createdAt,
-        });
-      } else {
-        const message = await this.formatOutgoingHistoryMessage(anyMessage);
-        formattedMessages.push({
-          ...message,
-          author: 'chatbot',
-          read: true, // Temporary fix as read is false in the bd
-          mid: messageMid,
-          handover: !!anyMessage.handover,
-          createdAt: anyMessage.createdAt,
-        });
-      }
-    }
-
-    return formattedMessages;
-  }
-
-  private normalizeThreadId(raw: unknown): string | undefined {
-    if (typeof raw !== 'string') {
-      return undefined;
-    }
-    const value = raw.trim();
-
-    return value.length > 0 ? value : undefined;
-  }
-
-  private getThreadIdFromQuery(req: SocketRequest): string | undefined {
-    const raw = req.query.thread_id;
-    const candidate = Array.isArray(raw) ? raw[0] : raw;
-
-    return this.normalizeThreadId(candidate);
-  }
-
-  private getThreadIdFromBody(req: SocketRequest): string | undefined {
-    const body = req.body as { thread_id?: unknown } | undefined;
-
-    return this.normalizeThreadId(body?.thread_id);
-  }
-
-  private async resolveThreadForHistory(
-    req: SocketRequest,
-  ): Promise<Thread | null> {
-    const profile = req.session.web?.profile;
-    if (!profile?.id) {
-      return null;
-    }
-
-    const explicitThreadId =
-      this.getThreadIdFromQuery(req) ?? this.getThreadIdFromBody(req);
-    const thread = await this.threadService.resolveThread({
-      subscriberId: profile.id,
-      explicitThreadId,
-    });
-
-    if (req.session.web) {
-      req.session.web.threadId = thread?.id;
-    }
-
-    return thread;
-  }
-
-  /**
-   * Fetches the messaging history from the DB.
-   * @param req - Either an HTTP Express request or a WS SocketRequest (synthetic)
-   * @param [until=new Date()] - Date before which to fetch
-   * @param [n=30] - Number of messages to fetch
-   * @returns Promise resolving to an array of messages.
-   * Fetches the last 'n' messages for the session profile up to the given date.
-   */
-  protected async fetchHistory(
-    req: SocketRequest,
-    until: Date = new Date(),
-    n: number = 30,
-  ): Promise<Web.Message[]> {
-    const thread = await this.resolveThreadForHistory(req);
-    if (thread) {
-      const messages = await this.messageService.findHistoryUntilDate(
-        thread,
-        until,
-        n,
-      );
-
-      return await this.formatMessages(messages.reverse() as AnyMessage[]);
-    }
-
-    return [];
-  }
-
   /**
    * Verify the origin against whitelisted domains.
    *
@@ -404,173 +272,45 @@ export default abstract class BaseWebChannelHandler<N extends ChannelName>
   private async ensureValidCors(
     req: SocketRequest,
     res: Response | SocketResponse,
-  ) {
-    // Check if we have an origin header...
-    if (!req.headers?.origin) {
-      this.logger.debug('No origin ', req.headers);
-      throw new Error('CORS - No origin provided!');
-    }
-
-    const originUrl = new URL(req.headers.origin);
-    const allowedProtocols = new Set(['http:', 'https:']);
-    if (!allowedProtocols.has(originUrl.protocol)) {
-      throw new Error('CORS - Invalid origin!');
-    }
-
-    const settings = await this.getSettings<typeof WEB_CHANNEL_NAME>();
-    // Get the allowed origins
-    const origins: string[] = settings.allowed_domains.split(',');
-    const foundOrigin = origins
-      .filter((origin) => origin.trim() !== '*') // Skip "*"
-      .map((origin) => {
-        try {
-          return new URL(origin.trim()).origin;
-        } catch (error) {
-          this.logger.error(`Invalid URL in allowed domains: ${origin}`, error);
-
-          return null;
-        }
-      })
-      .filter(
-        (normalizedOrigin): normalizedOrigin is string =>
-          normalizedOrigin !== null,
-      )
-      .some((origin: string) => {
-        // If we find a whitelisted origin, send the Access-Control-Allow-Origin header
-        // to greenlight the request.
-        return origin === originUrl.origin;
-      });
+    source: Source,
+  ): Promise<void> {
+    const allowedDomains =
+      typeof source.settings.allowed_domains === 'string'
+        ? source.settings.allowed_domains
+        : '*';
 
-    if (!foundOrigin && !origins.includes('*')) {
-      // For HTTP requests, set the Access-Control-Allow-Origin header to '', which the browser will
-      // interpret as, 'no way Jose.'
-      res.set('Access-Control-Allow-Origin', '');
-      this.logger.debug('No origin found ', req.headers.origin);
-      throw new Error('CORS - Domain not allowed!');
-    } else {
-      res.set('Access-Control-Allow-Origin', originUrl.origin);
-    }
-    // Determine whether or not to allow cookies to be passed cross-origin
-    res.set('Access-Control-Allow-Credentials', 'true');
-    // This header lets a server whitelist headers that browsers are allowed to access
-    res.set('Access-Control-Expose-Headers', '');
-    // Handle preflight requests
-    if (req.method == 'OPTIONS') {
-      res.set('Access-Control-Allow-Methods', 'GET, POST');
-      res.set('Access-Control-Allow-Headers', 'content-type');
-    }
+    await this.sessionService.validateCors(req, res, allowedDomains);
   }
 
-  /**
-   * Makes sure that message request is legitimate.
-   *
-   * @param req
-   * @param res
-   */
-  private async validateSession(
+  protected async getOrCreateSession(
     req: SocketRequest,
-    res: Response | SocketResponse,
-  ): Promise<Subscriber | null> {
-    if (req.session.web?.profile?.id) {
-      return req.session.web.profile;
-    }
-
-    const body = req.body as { author?: unknown; data?: unknown } | undefined;
-    const authorForeignId =
-      typeof body?.author === 'string' && body.author.trim().length > 0
-        ? body.author.trim()
-        : undefined;
+    source: Source,
+  ): Promise<Subscriber> {
+    return this.sessionService.getOrCreateSession(req, source.id, () => {
+      const data = req.query;
 
-    if (authorForeignId) {
-      try {
-        const subscriber =
-          await this.subscriberService.findOneByForeignId(authorForeignId);
-        if (subscriber) {
-          const thread = await this.threadService.resolveThread({
-            subscriberId: subscriber.id,
-            explicitThreadId:
-              this.getThreadIdFromBody(req) ?? this.getThreadIdFromQuery(req),
-          });
-          req.session.web = {
-            profile: subscriber,
-            threadId: thread?.id,
-          };
-
-          this.logger.debug(
-            `Recovered missing web session from author ${authorForeignId}`,
-          );
-
-          return subscriber;
-        }
-      } catch (error) {
-        this.logger.warn(
-          `Unable to recover missing session from author ${authorForeignId}`,
-          error,
-        );
-      }
-    }
-
-    this.logger.warn('No session ID to be found!', req.session);
-    res.status(403).json({ err: 'Web Channel Handler : Unauthorized!' });
-
-    return null;
-  }
-
-  /**
-   * Get or create a session profile for the subscriber
-   *
-   * @param req
-   *
-   * @returns Subscriber's profile
-   */
-  protected async getOrCreateSession(req: SocketRequest): Promise<Subscriber> {
-    const data = req.query;
-    // Subscriber has already a session
-    const sessionProfile = req.session.web?.profile;
-    if (sessionProfile) {
-      const subscriber = await this.subscriberService.findOne(
-        sessionProfile.id,
-      );
-      if (!subscriber || !req.session.web) {
-        throw new Error('Subscriber session was not persisted in DB');
-      }
-      const thread = await this.threadService.resolveThread({
-        subscriberId: subscriber.id,
-        explicitThreadId: req.session.web.threadId,
-      });
-      req.session.web.profile = subscriber;
-      req.session.web.threadId = thread?.id;
-
-      return subscriber;
-    }
-
-    const newProfile: SubscriberCreateDto = {
-      foreignId: this.generateId(),
-      firstName: data.first_name ? data.first_name.toString() : 'Anon.',
-      lastName: data.last_name ? data.last_name.toString() : 'Web User',
-      assignedTo: null,
-      assignedAt: null,
-      lastvisit: new Date(),
-      retainedFrom: new Date(),
-      avatar: null,
-      channel: {
-        name: this.getName(),
-        data: this.getChannelAttributes(req),
-      },
-      language: '',
-      locale: '',
-      timezone: 0,
-      gender: 'male',
-      country: '',
-      labels: [],
-    };
-    const profile = await this.subscriberService.create(newProfile);
-
-    req.session.web = {
-      profile,
-    };
-
-    return profile;
+      return {
+        foreignId: this.generateId(),
+        firstName: data.first_name ? String(data.first_name) : 'Anon.',
+        lastName: data.last_name ? String(data.last_name) : 'Web User',
+        assignedTo: null,
+        assignedAt: null,
+        lastvisit: new Date(),
+        retainedFrom: new Date(),
+        avatar: null,
+        channel: {
+          name: this.getName(),
+          data: this.getChannelAttributes(req),
+        },
+        language: '',
+        locale: '',
+        timezone: 0,
+        gender: 'male',
+        country: '',
+        labels: [],
+        source: source.id,
+      };
+    });
   }
 
   /**
@@ -582,29 +322,37 @@ export default abstract class BaseWebChannelHandler<N extends ChannelName>
   protected async subscribe(
     req: SocketRequest,
     res: Response | SocketResponse,
-  ) {
+    source: Source,
+  ): Promise<void> {
     this.logger.debug('subscribe (isSocket=true)');
     try {
-      const profile = await this.getOrCreateSession(req);
+      const profile = await this.getOrCreateSession(req, source);
+      const profileForeignId = profile.foreignId;
+      if (!profileForeignId) {
+        throw new Error('Session profile foreignId is missing');
+      }
       try {
-        await req.socket.join(profile.foreignId);
+        await req.socket.join(profileForeignId);
       } catch (err) {
         this.logger.error('Unable to subscribe via websocket', err);
       }
-      // Fetch message history
       const criteria =
-        'since' in req.query ? req.query.since : req.body?.since || undefined;
-      const messages = await this.fetchHistory(req, criteria);
+        'since' in req.query ? req.query.since : (req.body?.since ?? undefined);
+      const messages = await this.historyService.fetchHistoryForRequest(
+        req,
+        this.sessionService,
+        this.formatCtx(source.id),
+        criteria,
+      );
 
-      return res.status(200).json({
+      res.status(200).json({
         profile,
         messages,
         thread_id: req.session.web?.threadId ?? null,
       });
     } catch (err) {
       this.logger.warn('Unable to subscribe ', err);
-
-      return res.status(500).json({ err: 'Unable to subscribe' });
+      res.status(500).json({ err: 'Unable to subscribe' });
     }
   }
 
@@ -614,6 +362,7 @@ export default abstract class BaseWebChannelHandler<N extends ChannelName>
    * @param req - The WebSocket request containing the session and the file data.
    * @returns A Promise that resolves to the stored `Attachment`, or `null` if
    *          the session is invalid or no file is provided.
+   * @throws Error if missing file payload.
    * @throws Error if the max upload size is exceeded.
    * @throws Error when storing the uploaded file fails.
    */
@@ -626,8 +375,6 @@ export default abstract class BaseWebChannelHandler<N extends ChannelName>
 
         return null;
       }
-
-      // Check if any file is provided
       if (type !== Web.InboundMessageType.file) {
         this.logger.debug('No files provided');
 
@@ -637,6 +384,10 @@ export default abstract class BaseWebChannelHandler<N extends ChannelName>
         throw new Error('File payload is missing');
       }
 
+      const { name: fileName, type: mimeType } = data as {
+        name: string;
+        type: string;
+      };
       const size = Buffer.byteLength(data.file);
 
       if (size > config.parameters.maxUploadSize) {
@@ -644,9 +395,9 @@ export default abstract class BaseWebChannelHandler<N extends ChannelName>
       }
 
       return await this.attachmentService.store(data.file, {
-        name: data.name,
+        name: fileName,
         size,
-        type: data.type,
+        type: mimeType,
         resourceRef: AttachmentResourceRef.MessageAttachment,
         access: AttachmentAccess.Private,
         createdByRef: AttachmentCreatedByRef.Subscriber,
@@ -658,43 +409,16 @@ export default abstract class BaseWebChannelHandler<N extends ChannelName>
     }
   }
 
-  /**
-   * Returns the request client IP address
-   *
-   * @param req Either a HTTP request or a WS Request (Synthetic object)
-   *
-   * @returns IP Address
-   */
-  protected getIpAddress(req: SocketRequest): string {
-    return req.socket.handshake.address;
-  }
-
-  /**
-   * Return subscriber channel specific attributes
-   *
-   * @param req Either a HTTP Express request or a WS request (Synthetic Object)
-   *
-   * @returns The subscriber channel's attributes
-   */
-  getChannelAttributes(
-    req: SocketRequest,
-  ): SubscriberChannelDict[typeof WEB_CHANNEL_NAME] {
-    return {
-      isSocket: true,
-      ipAddress: this.getIpAddress(req),
-      agent: req.headers['user-agent'] || 'browser',
-    };
-  }
-
   /**
    * Handle channel event (probably a message)
    *
-   * @param req Either a HTTP Express request or a WS request (Synthetic Object)
-   * @param res Either a HTTP Express response or a WS response (Synthetic Object)
+   * @param req - WS request (Synthetic Object)
+   * @param res - Either a HTTP Express response or a WS response (Synthetic Object)
    */
   async handleEvent(
     req: SocketRequest,
     res: Response | SocketResponse,
+    source: Source,
     workflowId?: string,
   ): Promise<void> {
     if (!req.body) {
@@ -702,12 +426,13 @@ export default abstract class BaseWebChannelHandler<N extends ChannelName>
       res.status(400).json({ err: 'Web Channel Handler : Bad Request!' });
 
       return;
-    } else if (
+    }
+
+    if (
       typeof req.body === 'object' &&
       req.body !== null &&
       'data' in req.body
     ) {
-      // Parse json form data (in case of content-type multipart/form-data)
       const payload = req.body as { data?: unknown };
       payload.data =
         typeof payload.data === 'string'
@@ -715,10 +440,13 @@ export default abstract class BaseWebChannelHandler<N extends ChannelName>
           : payload.data;
     }
 
-    const profile = await this.validateSession(req, res);
-    if (!profile) {
-      return;
-    }
+    const profile = await this.sessionService.validateSession(
+      req,
+      res,
+      source.id,
+    );
+    if (!profile) return;
+
     const channelAttrs = this.getChannelAttributes(req);
     let events: Array<
       BaseWebInboundEvent<N> | WebMessageInboundEvent<N, Web.InboundMessage>
@@ -745,16 +473,15 @@ export default abstract class BaseWebChannelHandler<N extends ChannelName>
     }
 
     const explicitThreadId =
-      this.getThreadIdFromBody(req) ??
-      this.getThreadIdFromQuery(req) ??
+      this.sessionService.getThreadIdFromBody(req) ??
+      this.sessionService.getThreadIdFromQuery(req) ??
       req.session.web?.threadId;
     const responseBody = events[0].getRaw();
 
     for (const event of events) {
       event.setHandler(this);
-      if (explicitThreadId) {
-        event.setThreadId(explicitThreadId);
-      }
+      event.setSourceContext(source.id, source.settings);
+      if (explicitThreadId) event.setThreadId(explicitThreadId);
       event.setInitiator(profile);
       event.setWorkflowId(workflowId);
 
@@ -764,17 +491,15 @@ export default abstract class BaseWebChannelHandler<N extends ChannelName>
           Web.InboundMessage
         >;
 
-        // Handle upload when files are provided
         if (messageEvent instanceof AttachmentMessageInboundEvent) {
           try {
             const attachment = await this.handleWsUpload(req);
-
             if (attachment) {
               messageEvent.setUploadedAttachment(attachment);
               messageEvent.setUploadedRawData(
                 AttachmentOrmEntity.getTypeByMime(attachment.type),
                 await this.channelAttachmentService.getPublicUrl(
-                  this.getName(),
+                  source.id,
                   attachment,
                 ),
               );
@@ -788,55 +513,47 @@ export default abstract class BaseWebChannelHandler<N extends ChannelName>
           }
         }
 
-        // Handle sync message sent by chatbot
         if (messageEvent.isSyncFromChatbot()) {
-          const thread = await this.threadService.resolveThread({
-            subscriberId: profile.id,
-            explicitThreadId,
-          });
+          const thread = await this.sessionService.resolveThreadForHistory(
+            req,
+            profile.id,
+          );
           if (!thread) {
             return void res.status(409).json({
               err: 'Web Channel Handler : No thread available before first user message',
             });
           }
-
           messageEvent.setThreadId(thread.id);
-          if (req.session.web) {
-            req.session.web.threadId = thread.id;
-          }
+          if (req.session.web) req.session.web.threadId = thread.id;
+
           const sentMessage: MessageCreateDto = {
             mid: messageEvent.getId(),
-            message: messageEvent.getMessage() as StdOutgoingMessage,
+            message: {
+              type: OutgoingMessageType.text,
+              data: { text: messageEvent.getText() },
+            },
             recipient: profile.id,
             thread: thread.id,
             read: true,
             delivery: true,
           };
-          this.eventEmitter.emit(
-            'hook:chatbot:sent',
-            sentMessage,
-            messageEvent,
-          );
-
+          this.channelEventBus.emitSent(sentMessage, messageEvent);
           continue;
         }
 
-        // Generate unique ID and handle message
         messageEvent.setMessageId(this.generateId());
-        // Force author id from session
-        messageEvent.setAuthorForeignId(profile.foreignId);
-        // Use a server-side timestamp so realtime clients can sort deterministically.
+        if (profile.foreignId) {
+          messageEvent.setAuthorForeignId(profile.foreignId);
+        }
         messageEvent.setCreatedAt(new Date());
 
         this.broadcast(profile, StdEventType.message, messageEvent.getRaw());
-        await this.eventEmitter.emitAsync('hook:chatbot:message', messageEvent);
-        const resolvedThreadId = messageEvent.getThreadId();
+        await this.channelEventBus.emitMessage(messageEvent);
 
+        const resolvedThreadId = messageEvent.getThreadId();
         if (resolvedThreadId) {
           messageEvent.setThreadIdOnRaw(resolvedThreadId);
-          if (req.session.web) {
-            req.session.web.threadId = resolvedThreadId;
-          }
+          if (req.session.web) req.session.web.threadId = resolvedThreadId;
         }
 
         continue;
@@ -844,120 +561,65 @@ export default abstract class BaseWebChannelHandler<N extends ChannelName>
 
       const type = event.getEventType();
       const threadId = event.getThreadId();
-
-      if (threadId) {
-        event.setThreadIdOnRaw(threadId);
-      }
+      if (threadId) event.setThreadIdOnRaw(threadId);
       this.broadcast(profile, type, event.getRaw());
-      this.eventEmitter.emit(`hook:chatbot:${type}`, event);
+      this.channelEventBus.emitStatusEvent(event);
     }
 
     res.status(200).json(responseBody);
   }
 
-  /**
-   * Checks if a given request is a socket request
-   *
-   * @param req Either a HTTP express request or a WS request
-   * @returns True if it's a WS request
-   */
-  isSocketRequest(req: Request | SocketRequest): req is SocketRequest {
-    return 'isSocket' in req && req.isSocket;
-  }
-
-  /**
-   * Process incoming Web Channel data (finding out its type and assigning it to its proper handler)
-   *
-   * @param req Either a HTTP Express request or a WS request (Synthetic Object)
-   * @param res Either a HTTP Express response or a WS response (Synthetic Object)
-   */
-  async handle(
-    req: Request | SocketRequest,
+  protected async processSocketGet(
+    req: SocketRequest,
     res: Response | SocketResponse,
-    workflowId?: string,
-  ) {
-    if (!this.isSocketRequest(req)) {
-      this.logger.warn(
-        'Web channel over HTTP is no longer supported. Use Socket.IO transport.',
-      );
-
-      return res
-        .status(403)
-        .json({ err: 'Web Channel Handler : Unauthorized!' });
-    }
-
+    source: Source,
+  ): Promise<void> {
     try {
-      await this.ensureValidCors(req, res);
-      if (req.method === 'GET') {
-        if (req.query._disconnect) {
-          req.session.web = undefined;
-
-          return res.status(200).json({ _disconnect: true });
-        } else {
-          // Handle webhook subscribe requests
-          return await this.subscribe(req, res);
-        }
-      } else {
-        // Handle incoming messages (through POST)
-        return this.handleEvent(req, res, workflowId);
+      await this.ensureValidCors(req, res, source);
+      if (req.query._disconnect) {
+        req.session.web = undefined;
+
+        return void res.status(200).json({ _disconnect: true });
       }
+      await this.subscribe(req, res, source);
     } catch (err) {
       this.logger.warn('Request check failed', err);
-
-      return res
-        .status(403)
-        .json({ err: 'Web Channel Handler : Unauthorized!' });
+      res.status(403).json({ err: 'Web Channel Handler : Unauthorized!' });
     }
   }
 
-  /**
-   * Returns a unique identifier for the subscriber
-   *
-   * @returns UUID
-   */
-  generateId(): string {
-    return `${this.name}-${uuidv4()}`;
-  }
-
-  /**
-   * Sends a message to the end-user using websocket
-   *
-   * @param subscriber - End-user toward which message will be sent
-   * @param type - The message to be sent (message, typing, ...)
-   * @param content - The message payload contain additional settings
-   * @param [excludedRooms=[]] - Array of room names to exclude from receiving the message.
-   */
-  private broadcast(
-    subscriber: Subscriber,
-    type: StdEventType,
-    content: any,
-    excludedRooms: string[] = [],
-  ): void {
-    this.websocketGateway.broadcast(subscriber, type, content, excludedRooms);
+  protected async processSocketPost(
+    req: SocketRequest,
+    res: Response | SocketResponse,
+    source: Source,
+    workflowId?: string,
+  ): Promise<void> {
+    try {
+      await this.ensureValidCors(req, res, source);
+      await this.handleEvent(req, res, source, workflowId);
+    } catch (err) {
+      this.logger.warn('Request check failed', err);
+      res.status(403).json({ err: 'Web Channel Handler : Unauthorized!' });
+    }
   }
 
-  /**
-   * Send a Web Channel Message to the end-user
-   *
-   * @param event - Incoming event/message being responded to
-   * @param envelope - The message to be sent {format, message}
-   * @param options - Might contain additional settings
-   *
-   * @returns The web's response, otherwise an error
-   */
-  async sendMessage(
+  protected async doSendMessage(
     event: MessageInboundEvent<N>,
-    envelope: StdOutgoingEnvelope,
+    envelope: StdOutgoingMessageEnvelope,
     options: ActionOptions,
   ): Promise<{ mid: string }> {
-    if (envelope.format === OutgoingMessageFormat.system) {
-      throw new UnsupportedOutgoingFormatError(envelope.format);
+    const sourceId = event.getSourceId();
+
+    if (!sourceId) {
+      throw new Error(
+        `Missing sourceId while sending ${this.getName()} outbound message`,
+      );
     }
 
-    const messageBase = await this.outboundMessageEncoder.encode(
-      envelope,
-      options ?? {},
-    );
+    const messageBase = await this.outboundMessageEncoder.encode(envelope, {
+      ...(options ?? {}),
+      sourceId,
+    });
     const subscriber = event.getInitiator();
     const message: Web.OutboundMessage = {
       ...messageBase,
@@ -967,15 +629,15 @@ export default abstract class BaseWebChannelHandler<N extends ChannelName>
       createdAt: new Date(),
       handover: !!(options && options.assignTo),
     };
-    const next = async (): Promise<any> => {
+    const send = async (): Promise<{ mid: string }> => {
       this.broadcast(subscriber, StdEventType.message, message);
 
       return { mid: message.mid };
     };
 
-    if (options && options.typing) {
+    if (options?.typing) {
       const autoTimeout =
-        message && message.data && 'text' in message.data
+        message?.data && 'text' in message.data
           ? message.data.text.length * 10
           : 1000;
       const timeout =
@@ -983,37 +645,13 @@ export default abstract class BaseWebChannelHandler<N extends ChannelName>
       try {
         await this.sendTypingIndicator(subscriber, timeout);
 
-        return next();
+        return send();
       } catch (err) {
         this.logger.error('Failed in sending typing indicator ', err);
       }
     }
 
-    return next();
-  }
-
-  /**
-   * Send a typing indicator (waterline) to the end user for a given duration
-   *
-   * @param recipient - The end-user object
-   * @param timeout - Duration of the typing indicator in milliseconds
-   */
-  async sendTypingIndicator(
-    recipient: Subscriber,
-    timeout: number,
-  ): Promise<void> {
-    return new Promise((resolve, reject) => {
-      try {
-        this.broadcast(recipient, StdEventType.typing, true);
-        setTimeout(() => {
-          this.broadcast(recipient, StdEventType.typing, false);
-
-          return resolve();
-        }, timeout);
-      } catch (err) {
-        reject(err);
-      }
-    });
+    return send();
   }
 
   /**
@@ -1027,22 +665,22 @@ export default abstract class BaseWebChannelHandler<N extends ChannelName>
     event: MessageInboundEvent<N>,
   ): Promise<SubscriberCreateDto> {
     const sender = event.getInitiator();
-    const {
-      id: _id,
-      createdAt: _createdAt,
-      updatedAt: _updatedAt,
-      ...rest
-    } = sender;
-    const subscriber: SubscriberCreateDto = {
+    if (!sender.source) {
+      throw new Error('Unable to resolve subscriber source for web channel');
+    }
+    const { id: _id, createdAt: _c, updatedAt: _u, ...rest } = sender;
+
+    return {
       ...rest,
-      channel: sender.channel,
+      source: sender.source,
+      channel: sender.channel as SubscriberChannelData<N>,
     };
-
-    return subscriber;
   }
 
   /**
    * Checks if the request is authorized to download a given attachment file.
+   * Can be overridden by the channel handler to customize, by default it shouldn't
+   * allow any client to download a subscriber attachment for example.
    *
    * @param attachment The attachment object
    * @param req - The HTTP express request object.
@@ -1050,26 +688,27 @@ export default abstract class BaseWebChannelHandler<N extends ChannelName>
    */
   public async hasDownloadAccess(attachment: Attachment, req: Request) {
     const subscriberId = req.session.web?.profile?.id;
-    if (attachment.access === AttachmentAccess.Public) {
-      return true;
-    } else if (!subscriberId) {
+
+    if (attachment.access === AttachmentAccess.Public) return true;
+
+    if (!subscriberId) {
       this.logger.warn(
         `Unauthorized access attempt to attachment ${attachment.id}`,
       );
 
       return false;
-    } else if (
+    }
+
+    if (
       attachment.createdByRef === AttachmentCreatedByRef.Subscriber &&
       subscriberId === attachment.createdBy
     ) {
-      // Either subscriber wants to access the attachment he sent
       return true;
-    } else {
-      // Or, he would like to access an attachment sent to him privately
-      return await this.messageService.isAttachmentAccessibleBySubscriber(
-        subscriberId,
-        attachment.id,
-      );
     }
+
+    return this.messageService.isAttachmentAccessibleBySubscriber(
+      subscriberId,
+      attachment.id,
+    );
   }
 }