Custom Modules Overview

Custom Modules are FDSE (Field / Delivery / Solutions Engineering) and client-specific extensions that add functionality to Convotic without modifying the core platform. They allow you to build bespoke integrations, workflow nodes, API endpoints, and background workers scoped to a single workspace.

What Custom Modules are for

Custom Modules are designed for scenarios where the built-in Blocks and Workflow nodes are not sufficient:

• Integrating with a proprietary or niche API that Convotic does not support natively.
• Adding custom business logic as a Workflow node (e.g., a pricing calculator, loyalty point lookup).
• Exposing a custom webhook endpoint for an external system.
• Running scheduled background jobs (e.g., nightly data sync).

Five extension points

Custom Modules can extend Convotic through five mechanisms:

Extension point	What it does	Example
Routes	Register custom HTTP endpoints under your workspace's API namespace.	A webhook receiver for a proprietary ERP system.
Workers	Register background message handlers that consume from Pub/Sub topics.	A worker that processes order events from a custom queue.
Nodes	Register custom Workflow node types that appear in the visual builder.	A "Loyalty Lookup" node that queries your loyalty database.
Blocks	Register entirely new Block integrations with their own connection flow.	A Block for a regional messaging platform.
Crons	Register scheduled jobs that run on a cron schedule.	A nightly sync that reconciles inventory with a warehouse API.

Getting started with @convotic/block-sdk

Custom Modules are built using the @convotic/block-sdk npm package.

Installation

npm install @convotic/block-sdk

Module structure

A Custom Module is a TypeScript file that exports a register function:

import { ConvoticModule } from "@convotic/block-sdk";

const module: ConvoticModule = {
  name: "my-custom-module",
  version: "1.0.0",

  register(sdk) {
    // Register routes, workers, nodes, blocks, or crons here
    sdk.registerRoute({ /* ... */ });
    sdk.registerWorkerHandler({ /* ... */ });
    sdk.registerNodeHandler({ /* ... */ });
  },
};

export default module;

Development workflow

1. Scaffold a new module:

   npx @convotic/block-sdk init my-module

2. Implement your extension points in src/index.ts.
3. Test locally:

   npx @convotic/block-sdk dev

4. Deploy to your workspace:

   npx @convotic/block-sdk deploy --workspace ws_abc123

ヒント

The dev command starts a local server that simulates the Convotic runtime, so you can test routes, workers, and nodes without deploying.

Detailed guides

• Custom Routes -- expose custom HTTP endpoints.
• Custom Workers -- process background messages.
• Custom Workflow Nodes -- add nodes to the visual builder.

Permissions and isolation

• Custom Modules run in an isolated sandbox scoped to your workspace.
• They have access to the Convotic SDK context (workspace data, contacts, conversations) but cannot access other workspaces.
• Routes are namespaced under /v1/modules/:moduleName/ to avoid conflicts.
• Workers consume from dedicated Pub/Sub subscriptions.