feat(dashboard, api-service): Slack quickstart flow (#10728)

Author: scopsy

apps/api/src/app/agents/agents.controller.ts

@@ -52,10 +52,10 @@ import { ListAgentsCommand } from './usecases/list-agents/list-agents.command';
 import { ListAgents } from './usecases/list-agents/list-agents.usecase';
 import { RemoveAgentIntegrationCommand } from './usecases/remove-agent-integration/remove-agent-integration.command';
 import { RemoveAgentIntegration } from './usecases/remove-agent-integration/remove-agent-integration.usecase';
-import { UpdateAgentIntegrationCommand } from './usecases/update-agent-integration/update-agent-integration.command';
-import { UpdateAgentIntegration } from './usecases/update-agent-integration/update-agent-integration.usecase';
 import { UpdateAgentCommand } from './usecases/update-agent/update-agent.command';
 import { UpdateAgent } from './usecases/update-agent/update-agent.usecase';
+import { UpdateAgentIntegrationCommand } from './usecases/update-agent-integration/update-agent-integration.command';
+import { UpdateAgentIntegration } from './usecases/update-agent-integration/update-agent-integration.usecase';
 
 @ThrottlerCategory(ApiRateLimitCategoryEnum.CONFIGURATION)
 @ApiCommonResponses()
@@ -84,10 +84,7 @@ export class AgentsController {
     description: 'Creates an agent scoped to the current environment. The identifier must be unique per environment.',
   })
   @RequirePermissions(PermissionsEnum.AGENT_WRITE)
-  createAgent(
-    @UserSession() user: UserSessionData,
-    @Body() body: CreateAgentRequestDto
-  ): Promise<AgentResponseDto> {
+  createAgent(@UserSession() user: UserSessionData, @Body() body: CreateAgentRequestDto): Promise<AgentResponseDto> {
     return this.createAgentUsecase.execute(
       CreateAgentCommand.create({
         userId: user._id,
@@ -96,6 +93,7 @@ export class AgentsController {
         name: body.name,
         identifier: body.identifier,
         description: body.description,
+        active: body.active,
       })
     );
   }
@@ -108,10 +106,7 @@ export class AgentsController {
       'Returns a cursor-paginated list of agents for the current environment. Use **after**, **before**, **limit**, **orderBy**, and **orderDirection** query parameters.',
   })
   @RequirePermissions(PermissionsEnum.AGENT_READ)
-  listAgents(
-    @UserSession() user: UserSessionData,
-    @Query() query: ListAgentsQueryDto
-  ): Promise<ListAgentsResponseDto> {
+  listAgents(@UserSession() user: UserSessionData, @Query() query: ListAgentsQueryDto): Promise<ListAgentsResponseDto> {
     return this.listAgentsUsecase.execute(
       ListAgentsCommand.create({
         user,
@@ -132,7 +127,8 @@ export class AgentsController {
   @ApiResponse(AgentIntegrationResponseDto, 201)
   @ApiOperation({
     summary: 'Link integration to agent',
-    description: 'Creates a link between an agent (by identifier) and an integration (by integration **identifier**, not the internal _id).',
+    description:
+      'Creates a link between an agent (by identifier) and an integration (by integration **identifier**, not the internal _id).',
   })
   @ApiNotFoundResponse({
     description: 'The agent or integration was not found.',
@@ -287,6 +283,7 @@ export class AgentsController {
         identifier,
         name: body.name,
         description: body.description,
+        active: body.active,
         behavior: body.behavior,
       })
     );

apps/api/src/app/agents/dtos/agent-integration-response.dto.ts

@@ -1,4 +1,4 @@
-import { ApiProperty } from '@nestjs/swagger';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 import { ChannelTypeEnum } from '@novu/shared';
 
 /** Picked integration fields embedded on an agent–integration link response. */
@@ -40,6 +40,9 @@ export class AgentIntegrationResponseDto {
   @ApiProperty()
   _organizationId: string;
 
+  @ApiPropertyOptional({ description: 'Set when the agent–integration link has been used (e.g. first credential resolution).' })
+  connectedAt?: string | null;
+
   @ApiProperty()
   createdAt: string;
 

apps/api/src/app/agents/dtos/agent-response.dto.ts

@@ -19,6 +19,9 @@ export class AgentResponseDto {
   @ApiPropertyOptional({ type: AgentBehaviorDto })
   behavior?: AgentBehaviorDto;
 
+  @ApiProperty()
+  active: boolean;
+
   @ApiProperty()
   _environmentId: string;
 

apps/api/src/app/agents/dtos/create-agent-request.dto.ts

@@ -1,6 +1,6 @@
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 import { SLUG_IDENTIFIER_REGEX, slugIdentifierFormatMessage } from '@novu/shared';
-import { IsNotEmpty, IsOptional, IsString, Matches } from 'class-validator';
+import { IsBoolean, IsNotEmpty, IsOptional, IsString, Matches } from 'class-validator';
 
 export class CreateAgentRequestDto {
   @ApiProperty()
@@ -20,4 +20,9 @@ export class CreateAgentRequestDto {
   @IsString()
   @IsOptional()
   description?: string;
+
+  @ApiPropertyOptional({ default: true })
+  @IsBoolean()
+  @IsOptional()
+  active?: boolean;
 }

apps/api/src/app/agents/dtos/update-agent-request.dto.ts

@@ -1,6 +1,6 @@
 import { ApiPropertyOptional } from '@nestjs/swagger';
-import { IsOptional, IsString, ValidateNested } from 'class-validator';
 import { Type } from 'class-transformer';
+import { IsBoolean, IsOptional, IsString, ValidateNested } from 'class-validator';
 
 import { AgentBehaviorDto } from './agent-behavior.dto';
 
@@ -15,6 +15,11 @@ export class UpdateAgentRequestDto {
   @IsOptional()
   description?: string;
 
+  @ApiPropertyOptional()
+  @IsBoolean()
+  @IsOptional()
+  active?: boolean;
+
   @ApiPropertyOptional({ type: AgentBehaviorDto })
   @ValidateNested()
   @Type(() => AgentBehaviorDto)

apps/api/src/app/agents/mappers/agent-response.mapper.ts

@@ -8,6 +8,7 @@ export function toAgentResponse(agent: AgentEntity): AgentResponseDto {
     name: agent.name,
     identifier: agent.identifier,
     description: agent.description,
+    active: agent.active,
     behavior: agent.behavior,
     _environmentId: agent._environmentId,
     _organizationId: agent._organizationId,
@@ -33,7 +34,6 @@ export function toAgentIntegrationResponse(
   link: AgentIntegrationEntity,
   integration: Pick<IntegrationEntity, '_id' | 'identifier' | 'name' | 'providerId' | 'channel' | 'active'>
 ): AgentIntegrationResponseDto {
-
   return {
     _id: link._id,
     _agentId: link._agentId,
@@ -47,6 +47,7 @@ export function toAgentIntegrationResponse(
     },
     _environmentId: link._environmentId,
     _organizationId: link._organizationId,
+    connectedAt: link.connectedAt ?? null,
     createdAt: link.createdAt,
     updatedAt: link.updatedAt,
   };

apps/api/src/app/agents/services/agent-config-resolver.service.ts

@@ -1,5 +1,5 @@
 import { Injectable, NotFoundException, UnprocessableEntityException } from '@nestjs/common';
-import { decryptCredentials, FeatureFlagsService } from '@novu/application-generic';
+import { decryptCredentials, FeatureFlagsService, PinoLogger } from '@novu/application-generic';
 import {
   AgentIntegrationRepository,
   AgentRepository,
@@ -46,7 +46,8 @@ export class AgentConfigResolver {
     private readonly agentRepository: AgentRepository,
     private readonly agentIntegrationRepository: AgentIntegrationRepository,
     private readonly integrationRepository: IntegrationRepository,
-    private readonly channelConnectionRepository: ChannelConnectionRepository
+    private readonly channelConnectionRepository: ChannelConnectionRepository,
+    private readonly logger: PinoLogger
   ) {}
 
   async resolve(agentId: string, integrationIdentifier: string): Promise<ResolvedAgentConfig> {
@@ -108,6 +109,17 @@ export class AgentConfigResolver {
       connectionAccessToken = connection.auth.accessToken;
     }
 
+    if (agentIntegration.connectedAt == null) {
+      await this.agentIntegrationRepository.updateOne(
+        {
+          _id: agentIntegration._id,
+          _environmentId: environmentId,
+          _organizationId: organizationId,
+        },
+        { $set: { connectedAt: new Date() } }
+      );
+    }
+
     return {
       platform,
       credentials,

apps/api/src/app/agents/services/agent-inbound-handler.service.ts

@@ -1,12 +1,18 @@
-import { Injectable } from '@nestjs/common';
+import { forwardRef, Inject, Injectable } from '@nestjs/common';
 import { PinoLogger } from '@novu/application-generic';
 import { ConversationActivitySenderTypeEnum, ConversationParticipantTypeEnum, ConversationRepository, SubscriberRepository } from '@novu/dal';
 import type { Message, Thread } from 'chat';
 import { AgentEventEnum } from '../dtos/agent-event.enum';
+import { HandleAgentReplyCommand } from '../usecases/handle-agent-reply/handle-agent-reply.command';
+import { HandleAgentReply } from '../usecases/handle-agent-reply/handle-agent-reply.usecase';
 import { ResolvedAgentConfig } from './agent-config-resolver.service';
 import { AgentConversationService } from './agent-conversation.service';
 import { AgentSubscriberResolver } from './agent-subscriber-resolver.service';
-import { type BridgeAction, BridgeExecutorService } from './bridge-executor.service';
+import { type BridgeAction, BridgeExecutorService, NoBridgeUrlError } from './bridge-executor.service';
+
+const ONBOARDING_NO_BRIDGE_REPLY_MARKDOWN = `*You're connected to Novu*
+
+Your bot is linked successfully. Go back to the *Novu dashboard* to complete onboarding.`;
 
 @Injectable()
 export class AgentInboundHandler {
@@ -16,7 +22,9 @@ export class AgentInboundHandler {
     private readonly conversationService: AgentConversationService,
     private readonly conversationRepository: ConversationRepository,
     private readonly bridgeExecutor: BridgeExecutorService,
-    private readonly subscriberRepository: SubscriberRepository
+    private readonly subscriberRepository: SubscriberRepository,
+    @Inject(forwardRef(() => HandleAgentReply))
+    private readonly handleAgentReply: HandleAgentReply
   ) {}
 
   async handle(
@@ -111,19 +119,39 @@ export class AgentInboundHandler {
       this.conversationService.getHistory(config.environmentId, conversation._id),
     ]);
 
-    await this.bridgeExecutor.execute({
-      event,
-      config,
-      conversation,
-      subscriber,
-      history,
-      message,
-      platformContext: {
-        threadId: thread.id,
-        channelId: thread.channelId,
-        isDM: thread.isDM,
-      },
-    });
+    try {
+      await this.bridgeExecutor.execute({
+        event,
+        config,
+        conversation,
+        subscriber,
+        history,
+        message,
+        platformContext: {
+          threadId: thread.id,
+          channelId: thread.channelId,
+          isDM: thread.isDM,
+        },
+      });
+    } catch (err) {
+      if (err instanceof NoBridgeUrlError) {
+        await this.handleAgentReply.execute(
+          HandleAgentReplyCommand.create({
+            userId: 'system',
+            environmentId: config.environmentId,
+            organizationId: config.organizationId,
+            conversationId: conversation._id,
+            agentIdentifier: agentId,
+            integrationIdentifier: config.integrationIdentifier,
+            reply: { text: ONBOARDING_NO_BRIDGE_REPLY_MARKDOWN },
+          })
+        );
+
+        return;
+      }
+
+      throw err;
+    }
   }
 
   async handleAction(

apps/api/src/app/agents/services/bridge-executor.service.ts

@@ -103,6 +103,13 @@ export interface AgentBridgeRequest {
   action: BridgeAction | null;
 }
 
+export class NoBridgeUrlError extends Error {
+  constructor(agentIdentifier: string) {
+    super(`No bridge URL configured for agent ${agentIdentifier}`);
+    this.name = 'NoBridgeUrlError';
+  }
+}
+
 @Injectable()
 export class BridgeExecutorService {
   constructor(
@@ -119,7 +126,7 @@ export class BridgeExecutorService {
 
       const bridgeUrl = await this.resolveBridgeUrl(config.environmentId, config.organizationId, agentIdentifier, event);
       if (!bridgeUrl) {
-        return;
+        throw new NoBridgeUrlError(agentIdentifier);
       }
 
       const secretKey = await this.getDecryptedSecretKey.execute(
@@ -133,6 +140,10 @@ export class BridgeExecutorService {
         this.logger.error(err, `[agent:${agentIdentifier}] Bridge delivery failed after ${MAX_RETRIES + 1} attempts`);
       });
     } catch (err) {
+      if (err instanceof NoBridgeUrlError) {
+        throw err;
+      }
+
       this.logger.error(err, `[agent:${agentIdentifier}] Bridge setup failed — skipping bridge call`);
     }
   }

apps/api/src/app/agents/services/chat-sdk.service.ts

@@ -1,4 +1,4 @@
-import { BadRequestException, Injectable, OnModuleDestroy } from '@nestjs/common';
+import { BadRequestException, forwardRef, Inject, Injectable, OnModuleDestroy } from '@nestjs/common';
 import { PinoLogger } from '@novu/application-generic';
 import type { Chat, Message, Thread } from 'chat';
 import { Request as ExpressRequest, Response as ExpressResponse } from 'express';
@@ -42,6 +42,7 @@ export class ChatSdkService implements OnModuleDestroy {
   constructor(
     private readonly logger: PinoLogger,
     private readonly agentConfigResolver: AgentConfigResolver,
+    @Inject(forwardRef(() => AgentInboundHandler))
     private readonly inboundHandler: AgentInboundHandler
   ) {
     this.instances = new LRUCache<string, Chat>({