integration-channel

Integration Channel Development

Table of Contents

1. Architecture Overview
2. Pre-Creation Confirmation — resolve name, auth type, platform credentials before coding
3. Phase 1: Integration Package — create integrations/<channel>/
4. Phase 2: Database — schema + register in 7 files
5. Phase 3: Registration — builder, worker, UI
6. Phase 4: Builder Feature — settings page + feature directory
7. Post-Creation Verification — lint, install, build
8. Platform Credentials — optional OAuth app credentials
9. Webhook Flow
10. Existing Integrations Reference

---

Architecture Overview

Integrations are standalone packages under integrations/ that implement the IntegrationDefinition contract from @chatbotx.io/sdk.

Flow: External platform → webhook → builder route → BullMQ queue → worker → integration handler

Pre-Creation Confirmation (MANDATORY)

Before writing any code, you MUST resolve the 3 questions below. Analyze the user's request first, ask only what's missing, then present a confirmation summary and wait.

Question 1: Integration name

Channel name → determines package name (@chatbotx.io/integration-<channel>), DB table (Integration<Channel>), all file paths.

Question 2: Auth fields

For EACH field: name, Zod type, required or optional. Infer types from context (e.g. "port" → z.number().int().positive()).

Question 3: Platform credentials

Confirmation Summary

Integration: <channel>
Auth type: custom / oauth2
Auth fields:
  - fieldA: z.string().min(1)        [required]
  - fieldB: z.number().int()          [required]
Platform credentials: YES / NO

Wait for user confirmation before proceeding.

---

Creating a New Integration — Execution Plan

After confirmation, execute these 4 phases in order. Each phase ends with a verification step.

Phase 1: Integration Package (create integrations/<channel>/)

Create 5 files. All are boilerplate — write them in a single batch.

Directory structure:

integrations/<channel>/
  package.json
  tsconfig.json
  src/
    index.ts
    schema.ts
    integration.ts
    handlers/
      webhook.ts

package.json:

{
  "name": "@chatbotx.io/integration-<channel>",
  "version": "0.0.1",
  "private": true,
  "type": "module",
  "exports": {
    ".": "./src/index.ts",
    "./**/*": "./src/**/*.ts"
  },
  "dependencies": {
    "@chatbotx.io/sdk": "workspace:*",
    "zod": "^4.3.6"
  },
  "devDependencies": {
    "@chatbotx.io/typescript-config": "workspace:*",
    "@types/node": "^24.10.4",
    "typescript": "^5"
  }
}

tsconfig.json:

{
  "extends": "@chatbotx.io/typescript-config/base.json",
  "include": ["src/**/*.ts"],
  "compilerOptions": { "strictNullChecks": true }
}

src/index.ts:

export * from "./integration";

src/schema.ts — fill in auth fields from confirmation:

import type { BaseConfig } from "@chatbotx.io/sdk"
import { customAuthSchema } from "@chatbotx.io/sdk"
import { z } from "zod"

export type <Channel>Config = BaseConfig

export const <channel>AuthSchema = customAuthSchema.extend({
  // confirmed auth fields here
})
export type <Channel>AuthValue = z.infer<typeof <channel>AuthSchema>

export type <Channel>Actions = Record<string, never>

src/integration.ts:

import {
  type BaseConfig,
  type HandleRequestProps,
  Integration,
  type IntegrationDefinition,
  type Oauth2AuthValue,
} from "@chatbotx.io/sdk"
import { webhookHandler } from "./handlers/webhook"
import type { <Channel>Actions, <Channel>AuthValue } from "./schema"

const config: IntegrationDefinition<BaseConfig, <Channel>AuthValue, <Channel>Actions> = {
  name: "<channel>",
  channels: { channel: { message: {} } },
  actions: {},
  async handleRequest(props: HandleRequestProps<BaseConfig>): Promise<string | number | Oauth2AuthValue> {
    const segments = new URL(props.req.url).pathname.split("/")
    const action = segments.pop()
    switch (action) {
      case "webhook":
        return await webhookHandler(props)
      default:
        throw new Error(`Not implemented: ${props.req.method} ${props.req.url}`)
    }
  },
  disconnect(_props: <Channel>AuthValue): Promise<void> {
    throw new Error("Method is not implemented.")
  },
}

export const integration = new Integration(config)

src/handlers/webhook.ts:

import type { HandleRequestProps } from "@chatbotx.io/sdk"
import type { <Channel>Config } from "../schema"

export const webhookHandler = async (props: HandleRequestProps<<Channel>Config>) => {
  const payload = await props.req.json()
  await props.queue?.add("incomingMessage", {
    type: "incomingMessage",
    data: {
      integrationType: "<channel>",
      integrationIdentifier: payload.identifier,
      payload,
    },
  })
  return "OK"
}

Phase 2: Database (create schema + register in 7 files)

Create 2 new files, edit 5 existing files. Do all edits in a single batch.

Create packages/database/src/schema/integration-<channel>.ts:

import { index, jsonb, pgTable, text, uniqueIndex } from "drizzle-orm/pg-core"
import { bigintAsString, sharedColumns } from "../partials/shared"
import { flowModel } from "./flow"
import { inboxModel } from "./inbox"
import { workspaceModel } from "./workspace"

export const integration<Channel>Model = pgTable(
  "Integration<Channel>",
  {
    ...sharedColumns,
    auth: jsonb().notNull(),
    name: text().notNull(),
    workspaceId: bigintAsString().notNull()
      .references(() => workspaceModel.id, { onDelete: "cascade", onUpdate: "cascade" }),
    inboxId: bigintAsString().notNull()
      .references(() => inboxModel.id, { onDelete: "cascade", onUpdate: "cascade" }),
  },
  (table) => [
    index("Integration<Channel>_workspaceId_idx").using("btree", table.workspaceId.asc().nullsLast()),
    uniqueIndex("Integration<Channel>_inboxId_key").using("btree", table.inboxId.asc().nullsLast()),
  ],
)

Create packages/database/src/relations/integration-<channel>.ts:

import { defineRelationsPart } from "drizzle-orm"
// biome-ignore lint/performance/noNamespaceImport: drizzle schema
import * as schema from "../schema"

export const integration<Channel>Relations = defineRelationsPart(schema, (r) => ({
  integration<Channel>Model: {
    workspace: r.one.workspaceModel({
      from: r.integration<Channel>Model.workspaceId, to: r.workspaceModel.id, optional: false,
    }),
    inbox: r.one.inboxModel({
      from: r.integration<Channel>Model.inboxId, to: r.inboxModel.id, optional: false,
    }),
  },
}))

Edit 5 registration files (all in one batch):

CRITICAL — relations/index.ts needs TWO edits:

1. Import: import { integration<Channel>Relations } from "./integration-<channel>"
2. Spread: ...integration<Channel>Relations, in the relations object

After editing, immediately read back each file to verify both import AND spread are present.

Phase 3: Registration (edit 6 files)

Integration registration (4 files, single batch):

CRITICAL — verify imports: After each StrReplace on integration.ts and integrations.ts, immediately read back lines 1-10 to confirm the import line is actually present. The import and the usage are TWO separate edits.

UI registration (2 files):

CRITICAL — ChannelType cascade: Adding a value to the channelTypes enum causes compile errors in every Record<ChannelType, ...> that doesn't include the new key. Grep for Record<ChannelType and Record<\n\s*ChannelType (multiline) to find and fix ALL hits.

Phase 3 checkpoint: Run pnpm lint and pnpm --filter <touched-workspace> check-types on the modified files. Fix any undeclared-variable or missing-import errors before continuing.

Phase 4: Builder Feature + Settings Page

Create the feature directory and settings page. This is standard feature-scaffold work.

Directory structure:

apps/builder/src/features/integration-<channel>/
  schema/
    mutation.ts
    resource.ts
  actions/
    create-<channel>.action.ts
    update-<channel>.action.ts
    delete-<channel>.action.ts
  queries/
    index.ts
  components/
    create-<channel>-form.tsx
    <channel>-disconnect.tsx
  <channel>-manage.tsx

Key patterns for integration features:

schema/mutation.ts — Zod schemas for create/update:

import { zodBigintAsString } from "@chatbotx.io/utils"
import { z } from "zod"

export const create<Channel>Request = z.object({
  name: z.string().min(1).max(40),
  workspaceId: zodBigintAsString().nullish(),
  // auth fields from confirmation
})
export type Create<Channel>Request = z.infer<typeof create<Channel>Request>

export const update<Channel>Request = create<Channel>Request.partial()
export type Update<Channel>Request = z.infer<typeof update<Channel>Request>

schema/resource.ts — Select schema for responses:

import { createSelectSchema, integration<Channel>Model } from "@chatbotx.io/database/schema"
import type { z } from "zod"

export const integration<Channel>Resource = createSelectSchema(integration<Channel>Model).pick({
  id: true,
  name: true,
})
export type Integration<Channel>Resource = z.infer<typeof integration<Channel>Resource>

actions/create-<channel>.action.ts — Create action pattern:

• Uses workspaceActionClient.bindArgsSchemas(workspaceIdrequestParams).inputSchema(schema).action(...)
• Creates Inbox + Integration<Channel> in a DB transaction
• The inbox channel value must match the enum value added in Phase 2: channelTypes.enum.<channel>
• The inbox name should be set from parsedInput.name
• All auth fields go into the auth JSONB column

actions/delete-<channel>.action.ts — Delete action pattern:

• Uses workspaceActionClient.bindArgsSchemas([zodBigintAsString(), zodBigintAsString()]).action(...)
• No .inputSchema() — delete has no input
• Runs the integration delete and inboxService.disconnect({ inboxId, tx }) inside the same db.transaction(...)
• Imports inboxService from @chatbotx.io/business; do not inline the inbox status update in the action
• CRITICAL: Every channel delete action must call inboxService.disconnect() inside its transaction after deleting the integration row. This keeps disconnected inboxes out of active inbox queries and prevents channel-specific drift.

queries/index.ts — Server-side queries:

"use server"
import { db, findOrFail } from "@chatbotx.io/database/client"
import { integration<Channel>Model } from "@chatbotx.io/database/schema"
import type { Integration<Channel>Model } from "@chatbotx.io/database/types"
import { assertCurrentUserCanAccessChatbot } from "@/lib/auth/utils"

export const listIntegration<Channel>s = async (input: { workspaceId: string }) => {
  await assertCurrentUserCanAccessChatbot(input.workspaceId)
  const data = await db.query.integration<Channel>Model.findMany({
    where: { workspaceId: input.workspaceId },
    orderBy: { createdAt: "desc" },
  })
  return { data }
}

components/create-<channel>-form.tsx — Form pattern:

• Uses useHookFormAction(createAction.bind(null, workspaceId), zodResolver(schema), ...)
• CRITICAL: Must call .bind(null, workspaceId) because the action uses bindArgsSchemas

components/<channel>-disconnect.tsx — Disconnect pattern:

• Renders <DisconnectIntegrationDialog> from @/features/common/components/disconnect-integration-dialog
• Passes featureLabel, open, onOpenChange, isPending, and onConfirm to the shared dialog
• Binds the action with useAction(deleteAction.bind(null, workspaceId, integrationId), ...) and calls execute() with NO arguments

<channel>-manage.tsx — Manage table:

• Uses use(promises) to unwrap server promises
• Shows table with integration data
• Add button links to /channels/create?channel=<channel>&workspaceId=...

Settings page — create @<channel>/page.tsx:

import { getIdFromParams } from "@chatbotx.io/utils"
import { notFound } from "next/navigation"
import { <Channel>Manage } from "@/features/integration-<channel>/<channel>-manage"
import { listIntegration<Channel>s } from "@/features/integration-<channel>/queries"

export default async function SettingChannel<Channel>Page(props: {
  params: Promise<{ workspaceId: string }>
}) {
  const workspaceId = getIdFromParams(await props.params, "workspaceId")
  if (!workspaceId) return notFound()
  const promises = listIntegration<Channel>s({ workspaceId })
  return <<Channel>Manage promises={promises} workspaceId={workspaceId} />
}

Settings layout — edit layout.tsx: Add "<channel>" to the CHANNELS array. That's the only edit needed — the type and props are derived automatically from the array.

Post-Creation Verification

Run these checks in order:

1. ReadLints on ALL modified files
2. pnpm fix — auto-fix formatting (ignore pre-existing errors in other files)
3. CI=true pnpm install --no-frozen-lockfile — link new workspace package (use CI=true to avoid TTY prompt)
4. pnpm turbo build — if it fails, read errors, fix, re-run

Common Build Errors

Platform Credentials (only if needed)

If platform credentials ARE needed, also update:

Logging

Never use console in integration code. Import @chatbotx.io/logger for shared packages, or the app-local logger for worker/builder code.

import logger from "@chatbotx.io/logger";

// ✅ correct — preserves stack trace
logger.error({ err: error, channel: "<channel>" }, "Webhook handler failed");

// ❌ wrong — stack trace lost
logger.error({ error }, "Webhook handler failed");

Always use err: error (not error: error) — pino's built-in serializer is registered under the err key.

Comment Handler Pattern

Some integrations (messenger, instagram-facebook) expose a comment channel alongside message. The structure mirrors message handlers:

handlers/
  comment/
    index.ts                    ← exports commentHandlers object
    actions.ts                  ← deleteComment, hideComment, likeComment, editComment
    outgoing-comment/
      index.ts                  ← sendComment

index.ts:

import { deleteComment, editComment, hideComment, likeComment } from "./actions"
import { sendComment } from "./outgoing-comment"

export const commentHandlers = {
  sendComment,
  editComment,
  deleteComment,
  likeComment,
  hideComment,
}

actions.ts — wrap API calls, catch errors, re-throw as mapToChannelError(error).

sendComment — requires message.contentAttributes.replyToCommentId (string); throw ChannelError(PAYLOAD_INVALID) if missing.

editComment — if the platform does not support editing comments (e.g. Facebook/Instagram), resolve immediately with no-op and log a warning.

Webhook routing — comment events arrive as changes entries with field === "comments". Parse with a typed Zod schema, then queue.add("incomingComment", { type: "incomingComment", data: { commentData: {...} } }).

Webhook Flow

1. External platform sends webhook to /integrations/<channel>/webhook
2. Builder route resolves integration config
3. handleRequest receives { config, req, queue }
4. Handler enqueues job: queue.add("incomingMessage", { type, data })
5. Integration worker calls allIntegrations[type].channels.channel.message.receiveMessage

White-label: register webhook URLs on the broker host

When white-label custom domains are in use, webhook URLs registered with the provider (and any URL shown in a platform-credential settings card for the reseller to copy) must use the broker host — getBrokerOrigin() / buildBrokerCallbackUrl() (apps/builder/src/lib/oauth-broker.ts) — not the tenant's custom domain. Providers that validate the registered host (e.g. WhatsApp/Meta, TikTok) cannot reach an unregistered branded domain, so a webhook on the reseller domain silently fails. See features/integration-whatsapp/actions/webhook-url.ts and docs/tenancy.md (provider-console registration runbook).

Existing Integrations Reference