feat(api-service,js,react): Telegram subscriber-link SDK + shared linking module fixes NV-8095 (#11619)

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: George Djabarov <djabarovgeorge@users.noreply.github.com>

Author: djabarovgeorge

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

@@ -29,11 +29,10 @@ import { EventsModule } from '../events/events.module';
 import { IntegrationModule } from '../integrations/integrations.module';
 import { KeylessModule } from '../keyless/keyless.module';
 import { SharedModule } from '../shared/shared.module';
+import { TelegramLinkingModule } from '../telegram-linking/telegram-linking.module';
 import { AgentConfigResolver } from './channels/agent-config-resolver.service';
 import { AgentIntegrationsController } from './channels/integrations/agent-integrations.controller';
-import { AgentsPublicController } from './channels/telegram-linking/agents-public.controller';
-import { TelegramMobileLinkTokenService } from './channels/telegram-linking/telegram-mobile-link-token.service';
-import { TelegramStartCodeService } from './channels/telegram-linking/telegram-start-code.service';
+import { AgentsPublicController } from './channels/slack-linking/agents-public.controller';
 import { InboundAckService } from './conversation-runtime/ack/inbound-ack.service';
 import { AgentActionTokenService } from './conversation-runtime/action-token/agent-action-token.service';
 import { AgentAttachmentStorage } from './conversation-runtime/conversation/agent-attachment-storage.service';
@@ -84,6 +83,7 @@ import { USE_CASES } from './usecases';
     ChannelEndpointsModule,
     ConnectModule,
     KeylessModule,
+    TelegramLinkingModule,
     forwardRef(() => IntegrationModule),
   ],
   controllers: [
@@ -144,8 +144,6 @@ import { USE_CASES } from './usecases';
     AgentEmailSender,
     OutboundGateway,
     McpOAuthDiscoveryService,
-    TelegramMobileLinkTokenService,
-    TelegramStartCodeService,
     CalculateLimitNovuIntegration,
     CalculateDemoClaudeQuota,
     CreateOrUpdateSubscriberUseCase,

apps/api/src/app/agents/channels/index.ts

@@ -1,3 +1,3 @@
 export { AgentConfigResolver } from './agent-config-resolver.service';
 export { AgentIntegrationsController } from './integrations/agent-integrations.controller';
-export { AgentsPublicController } from './telegram-linking/agents-public.controller';
+export { AgentsPublicController } from './slack-linking/agents-public.controller';

apps/api/src/app/agents/channels/integrations/add-agent-integration/add-agent-integration.usecase.ts

@@ -20,6 +20,7 @@ import {
 } from '@novu/dal';
 import {
   ApiServiceLevelEnum,
+  ChatProviderIdEnum,
   EmailProviderIdEnum,
   EnvironmentTypeEnum,
   FeatureNameEnum,
@@ -144,6 +145,21 @@ export class AddAgentIntegration {
       throw new ConflictException('This integration is already linked to the agent.');
     }
 
+    if (integration.providerId === ChatProviderIdEnum.Telegram) {
+      const linkedElsewhere = await this.agentIntegrationRepository.findOne(
+        {
+          _integrationId: integration._id,
+          _environmentId: command.environmentId,
+          _organizationId: command.organizationId,
+        },
+        ['_agentId']
+      );
+
+      if (linkedElsewhere && linkedElsewhere._agentId !== agent._id) {
+        throw new ConflictException('Integration is already linked to a different agent');
+      }
+    }
+
     // Revives a tombstoned (disconnected) link when one exists for this pair —
     // a plain create would violate the unique (_agentId, _integrationId) index.
     const link = await this.agentIntegrationRepository.createOrReviveLink({

apps/api/src/app/agents/channels/integrations/agent-integrations.controller.ts

@@ -46,13 +46,8 @@ import {
   UpdateAgentInboxSharedRequestDto,
   UpdateAgentIntegrationRequestDto,
 } from '../../shared/dtos';
-import { ConfigureTelegramWebhookResponseDto } from '../../shared/dtos/configure-telegram-webhook-response.dto';
 import { ConfigureWhatsAppWebhookResponseDto } from '../../shared/dtos/configure-whatsapp-webhook-response.dto';
 import { IssueSlackSetupLinkResponseDto } from '../../shared/dtos/issue-slack-setup-link-response.dto';
-import { IssueTelegramMobileLinkRequestDto } from '../../shared/dtos/issue-telegram-mobile-link-request.dto';
-import { IssueTelegramMobileLinkResponseDto } from '../../shared/dtos/issue-telegram-mobile-link-response.dto';
-import { IssueTelegramSubscriberLinkRequestDto } from '../../shared/dtos/issue-telegram-subscriber-link-request.dto';
-import { IssueTelegramSubscriberLinkResponseDto } from '../../shared/dtos/issue-telegram-subscriber-link-response.dto';
 import { SendAgentTestEmailRequestDto } from '../../shared/dtos/send-agent-test-email-request.dto';
 import { SendAgentWelcomeMessageRequestDto } from '../../shared/dtos/send-agent-welcome-message-request.dto';
 import {
@@ -61,12 +56,6 @@ import {
 } from '../../shared/dtos/send-whatsapp-test-template.dto';
 import { IssueSlackSetupLinkCommand } from '../slack-linking/issue-slack-setup-link/issue-slack-setup-link.command';
 import { IssueSlackSetupLink } from '../slack-linking/issue-slack-setup-link/issue-slack-setup-link.usecase';
-import { ConfigureTelegramAgentWebhookCommand } from '../telegram/configure-telegram-agent-webhook/configure-telegram-agent-webhook.command';
-import { ConfigureTelegramAgentWebhook } from '../telegram/configure-telegram-agent-webhook/configure-telegram-agent-webhook.usecase';
-import { IssueTelegramMobileLinkCommand } from '../telegram-linking/issue-telegram-mobile-link/issue-telegram-mobile-link.command';
-import { IssueTelegramMobileLink } from '../telegram-linking/issue-telegram-mobile-link/issue-telegram-mobile-link.usecase';
-import { IssueTelegramSubscriberLinkCommand } from '../telegram-linking/issue-telegram-subscriber-link/issue-telegram-subscriber-link.command';
-import { IssueTelegramSubscriberLink } from '../telegram-linking/issue-telegram-subscriber-link/issue-telegram-subscriber-link.usecase';
 import { ConfigureWhatsAppWebhookCommand } from '../whatsapp/configure-whatsapp-webhook/configure-whatsapp-webhook.command';
 import { ConfigureWhatsAppWebhook } from '../whatsapp/configure-whatsapp-webhook/configure-whatsapp-webhook.usecase';
 import { SendWhatsAppTestTemplateCommand } from '../whatsapp/send-whatsapp-test-template/send-whatsapp-test-template.command';
@@ -96,10 +85,7 @@ export class AgentIntegrationsController {
     private readonly sendAgentWelcomeMessageUsecase: SendAgentWelcomeMessage,
     private readonly configureWhatsAppWebhookUsecase: ConfigureWhatsAppWebhook,
     private readonly sendWhatsAppTestTemplateUsecase: SendWhatsAppTestTemplate,
-    private readonly configureTelegramAgentWebhookUsecase: ConfigureTelegramAgentWebhook,
-    private readonly issueTelegramMobileLinkUsecase: IssueTelegramMobileLink,
     private readonly issueSlackSetupLinkUsecase: IssueSlackSetupLink,
-    private readonly issueTelegramSubscriberLinkUsecase: IssueTelegramSubscriberLink,
     private readonly updateAgentInboxSharedUsecase: UpdateAgentInboxShared
   ) {}
 
@@ -365,70 +351,6 @@ export class AgentIntegrationsController {
     );
   }
 
-  @Post('/:identifier/integrations/:integrationId/telegram/configure')
-  @ExternalApiAccessible()
-  @KeylessAccessible()
-  @HttpCode(HttpStatus.OK)
-  @ApiResponse(ConfigureTelegramWebhookResponseDto, 200)
-  @ApiOperation({
-    summary: 'Configure Telegram bot webhook',
-    description: `Registers the Novu agent webhook URL with Telegram for the specified integration,
-       generates a cryptographic secret token for webhook verification,
-       and persists it on the integration. Re-running rotates the secret.`,
-  })
-  @ApiNotFoundResponse({
-    description: 'The agent, integration, or agent-integration link was not found.',
-  })
-  @RequirePermissions(PermissionsEnum.AGENT_WRITE)
-  updateTelegramWebhook(
-    @UserSession() user: UserSessionData,
-    @Param('identifier') identifier: string,
-    @Param('integrationId') integrationId: string
-  ): Promise<ConfigureTelegramWebhookResponseDto> {
-    return this.configureTelegramAgentWebhookUsecase.execute(
-      ConfigureTelegramAgentWebhookCommand.create({
-        userId: user._id,
-        environmentId: user.environmentId,
-        organizationId: user.organizationId,
-        agentIdentifier: identifier,
-        integrationId,
-      })
-    );
-  }
-
-  @Post('/:identifier/integrations/:integrationId/telegram/mobile-link')
-  @ExternalApiAccessible()
-  @KeylessAccessible()
-  @HttpCode(HttpStatus.OK)
-  @ApiResponse(IssueTelegramMobileLinkResponseDto, 200)
-  @ApiOperation({
-    summary: 'Issue a short-lived Telegram mobile setup link',
-    description:
-      'Issues a signed, single-use link (TTL = 5 minutes) that can be opened on a mobile device to finish ' +
-      'configuring a Telegram bot without re-authenticating. Telegram-only.',
-  })
-  @ApiNotFoundResponse({
-    description: 'The agent, integration, or agent-integration link was not found.',
-  })
-  @RequirePermissions(PermissionsEnum.AGENT_WRITE)
-  createTelegramMobileLink(
-    @UserSession() user: UserSessionData,
-    @Param('identifier') identifier: string,
-    @Param('integrationId') integrationId: string,
-    @Body() body?: IssueTelegramMobileLinkRequestDto
-  ): Promise<IssueTelegramMobileLinkResponseDto> {
-    return this.issueTelegramMobileLinkUsecase.execute(
-      IssueTelegramMobileLinkCommand.create({
-        userId: user._id,
-        environmentId: user.environmentId,
-        organizationId: user.organizationId,
-        agentIdentifier: identifier,
-        integrationId,
-        subscriberId: body?.subscriberId,
-      })
-    );
-  }
-
   @Post('/:identifier/integrations/:integrationId/slack/setup-link')
   @ExternalApiAccessible()
   @KeylessAccessible()
@@ -459,38 +381,4 @@ export class AgentIntegrationsController {
       })
     );
   }
-
-  @Post('/:identifier/integrations/:integrationId/telegram/subscriber-link')
-  @ExternalApiAccessible()
-  @KeylessAccessible()
-  @HttpCode(HttpStatus.OK)
-  @ApiResponse(IssueTelegramSubscriberLinkResponseDto, 200)
-  @ApiOperation({
-    summary: 'Issue a Telegram subscriber-link deep link',
-    description:
-      'Issues a short-lived opaque start code and returns a Telegram `t.me/<bot>?start=<code>` deep link. When ' +
-      'opened, Telegram sends `/start <code>` to the bot; the agent webhook consumes the code server-side and ' +
-      'creates a `telegram_chat` channel endpoint so notifications can reach that subscriber via Telegram.',
-  })
-  @ApiNotFoundResponse({
-    description: 'The agent, integration, agent-integration link, or subscriber was not found.',
-  })
-  @RequirePermissions(PermissionsEnum.AGENT_WRITE)
-  createTelegramSubscriberLink(
-    @UserSession() user: UserSessionData,
-    @Param('identifier') identifier: string,
-    @Param('integrationId') integrationId: string,
-    @Body() body: IssueTelegramSubscriberLinkRequestDto
-  ): Promise<IssueTelegramSubscriberLinkResponseDto> {
-    return this.issueTelegramSubscriberLinkUsecase.execute(
-      IssueTelegramSubscriberLinkCommand.create({
-        userId: user._id,
-        environmentId: user.environmentId,
-        organizationId: user.organizationId,
-        agentIdentifier: identifier,
-        integrationId,
-        subscriberId: body.subscriberId,
-      })
-    );
-  }
 }

apps/api/src/app/agents/channels/slack-linking/agents-public.controller.ts

@@ -0,0 +1,63 @@
+import { Body, Controller, Get, HttpCode, HttpStatus, Post, Query } from '@nestjs/common';
+import { ApiExcludeController, ApiOperation } from '@nestjs/swagger';
+import { ApiRateLimitCategoryEnum } from '@novu/shared';
+
+import { ThrottlerCategory } from '../../../rate-limiting/guards';
+import { ApiCommonResponses, ApiResponse } from '../../../shared/framework/response.decorator';
+import {
+  ConsumeSlackSetupLinkRequestDto,
+  ConsumeSlackSetupLinkResponseDto,
+} from '../../shared/dtos/consume-slack-setup-link.dto';
+import { SlackSetupLinkStatusResponseDto } from '../../shared/dtos/slack-setup-link-status-response.dto';
+import { ConsumeSlackSetupLinkCommand } from './consume-slack-setup-link/consume-slack-setup-link.command';
+import { ConsumeSlackSetupLink } from './consume-slack-setup-link/consume-slack-setup-link.usecase';
+import { GetSlackSetupLinkStatusCommand } from './get-slack-setup-link-status/get-slack-setup-link-status.command';
+import {
+  GetSlackSetupLinkStatus,
+  type GetSlackSetupLinkStatusResult,
+} from './get-slack-setup-link-status/get-slack-setup-link-status.usecase';
+
+/**
+ * Public, unauthenticated agent endpoints (no session) for Slack setup links.
+ */
+@ThrottlerCategory(ApiRateLimitCategoryEnum.CONFIGURATION)
+@ApiCommonResponses()
+@Controller('/agents/public')
+@ApiExcludeController()
+export class AgentsPublicController {
+  constructor(
+    private readonly getSlackSetupLinkStatusUsecase: GetSlackSetupLinkStatus,
+    private readonly consumeSlackSetupLinkUsecase: ConsumeSlackSetupLink
+  ) {}
+
+  @Get('slack/setup/status')
+  @HttpCode(HttpStatus.OK)
+  @ApiResponse(SlackSetupLinkStatusResponseDto, 200)
+  @ApiOperation({
+    summary: 'Check the status of a Slack setup link',
+    description:
+      'Returns whether a Slack setup token is still usable. Designed to be called from the ' +
+      'setup landing page before showing the credentials form.',
+  })
+  async getSlackSetupStatus(@Query('token') token: string): Promise<GetSlackSetupLinkStatusResult> {
+    return this.getSlackSetupLinkStatusUsecase.execute(GetSlackSetupLinkStatusCommand.create({ token: token ?? '' }));
+  }
+
+  @Post('slack/setup')
+  @HttpCode(HttpStatus.OK)
+  @ApiResponse(ConsumeSlackSetupLinkResponseDto, 200)
+  @ApiOperation({
+    summary: 'Consume a Slack setup link',
+    description:
+      'Validates the setup token, runs Slack quick-setup with the supplied App Configuration Token, ' +
+      'and creates the Slack app from the Novu manifest. The token becomes invalid after a successful call.',
+  })
+  async consumeSlackSetup(@Body() body: ConsumeSlackSetupLinkRequestDto): Promise<ConsumeSlackSetupLinkResponseDto> {
+    return this.consumeSlackSetupLinkUsecase.execute(
+      ConsumeSlackSetupLinkCommand.create({
+        token: body.token,
+        configToken: body.configToken,
+      })
+    );
+  }
+}

apps/api/src/app/agents/channels/slack-linking/consume-slack-setup-link/consume-slack-setup-link.usecase.ts

@@ -14,7 +14,7 @@ import {
   InvalidTelegramMobileTokenError,
   SlackAgentSetupLinkPayload,
   TelegramMobileLinkTokenService,
-} from '../../telegram-linking/telegram-mobile-link-token.service';
+} from '../../../../telegram-linking/telegram-mobile-link-token.service';
 import { ConsumeSlackSetupLinkCommand } from './consume-slack-setup-link.command';
 
 export interface ConsumeSlackSetupLinkResult {

apps/api/src/app/agents/channels/slack-linking/get-slack-setup-link-status/get-slack-setup-link-status.usecase.ts

@@ -6,7 +6,7 @@ import {
   InvalidTelegramMobileTokenError,
   SlackAgentSetupLinkPayload,
   TelegramMobileLinkTokenService,
-} from '../../telegram-linking/telegram-mobile-link-token.service';
+} from '../../../../telegram-linking/telegram-mobile-link-token.service';
 import { GetSlackSetupLinkStatusCommand } from './get-slack-setup-link-status.command';
 
 export type GetSlackSetupLinkStatusResult =

apps/api/src/app/agents/channels/slack-linking/issue-slack-setup-link/issue-slack-setup-link.usecase.ts

@@ -2,7 +2,7 @@ import { BadRequestException, Injectable, NotFoundException } from '@nestjs/comm
 import { AgentIntegrationRepository, AgentRepository, IntegrationRepository } from '@novu/dal';
 import { ChatProviderIdEnum } from '@novu/shared';
 
-import { TelegramMobileLinkTokenService } from '../../telegram-linking/telegram-mobile-link-token.service';
+import { TelegramMobileLinkTokenService } from '../../../../telegram-linking/telegram-mobile-link-token.service';
 import { IssueSlackSetupLinkCommand } from './issue-slack-setup-link.command';
 
 export interface IssueSlackSetupLinkResult {