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. Multi-Account Pickers
11. 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>/)

Copy integrations/telegram/ — a live, minimal customAuthSchema integration. Copying a sibling keeps dependency versions and the exports/scripts blocks correct; a hand-written template drifts on every bump.

cp -r integrations/telegram integrations/<channel>

Then rename throughout and strip Telegram-specific logic. The five files that matter:

The Integration class and customAuthSchema come from @chatbotx.io/sdk (packages/sdk/src/lib/integration.ts, packages/sdk/src/lib/auth/index.ts).

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 7 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 (3 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(workspaceIdAndIdRequestParams).inputSchema(schema).action(...) — see apps/builder/src/features/integration-telegram/actions/disconnect.action.ts:17
• 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
• Calls integration<Channel>Service.delete({ workspaceId, id }) — the service (not the action) owns the transaction, deletes the integration row, and calls inboxService.disconnect({ inboxId, tx }) inside it. The action never opens its own db.transaction(...).
• CRITICAL: Every channel delete service method must call inboxService.disconnect() inside the same transaction as the integration-row delete. This keeps disconnected inboxes out of active inbox queries and prevents channel-specific drift.

queries/index.ts — A thin adapter over the service, per .agents/rules/data-access.md: resolve session context → plain params → call the service → shape the response. No db / @chatbotx.io/database/schema import, and no "use server" (a query file is not a server-action module).

import { integration<Channel>Service } from "@chatbotx.io/business"
import { assertCurrentUserCanAccessChatbot } from "@/lib/auth/utils"

export const listIntegration<Channel>s = async (input: { workspaceId: string }) => {
  await assertCurrentUserCanAccessChatbot(input.workspaceId)
  return { data: await integration<Channel>Service.listByWorkspaceId(input.workspaceId) }
}

Do not copy a sibling channel's queries/index.ts verbatim. Every existing channel feature (e.g. apps/builder/src/features/integration-telegram/queries/index.ts) still opens with import { db } from "@chatbotx.io/database/client" — those are legacy exceptions that predate the rule, not the pattern. New code calls a service.

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 settings/channels/<channel>/page.tsx:

Each channel's settings panel is a real nested route (apps/builder/src/app/space/[workspaceId]/(settings)/settings/channels/<channel>/page.tsx), not a parallel-route slot. The accordion rows render in layout.tsx (from MANAGEABLE_CHANNELS filtered by visibility policy); opening a row navigates to this route so only this channel's server/client graph loads. Guard the page with requireVisibleChannel — it 404s for hidden channels and returns the request-scoped ChannelPolicy:

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"
import { requireVisibleChannel } from "@/lib/workspace/require-visible-channel"
import { resolveChannelCreatable } from "@/lib/workspace/resolve-channel-creatable"

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

  await requireVisibleChannel(workspaceId, "<channel>")

  const promises = listIntegration<Channel>s({ workspaceId })
  const canCreate = await resolveChannelCreatable(workspaceId, "<channel>")
  return <<Channel>Manage canCreate={canCreate} promises={promises} workspaceId={workspaceId} />
}

For credential-backed channels, keep the policy the guard returns — its ownerId is the tenant-aware owner, so no extra workspace/owner fetch:

const policy = await requireVisibleChannel(workspaceId, "<channel>")
const credential = await platformCredentialService.resolveForOwner({
  ownerId: policy.ownerId,
  type: "<channel>",
})

No settings-layout edit is needed: the row appears once the CHANNEL_CAPABILITIES entry marks the channel manageable (Phase 3, file 7). A capability entry without this page 404s loudly when the row is clicked.

Post-Creation Verification

Run these checks in order:

1. CI=true pnpm install --no-frozen-lockfile — link the new workspace package (CI=true avoids the TTY prompt)
2. pnpm fix then pnpm lint — auto-fix formatting, then confirm clean (ignore pre-existing errors in untouched files)
3. 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

Use the structured logger, never console, and log with { err: error } — see repo invariant 20 in AGENTS.md.

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).

Multi-Account Pickers

Channels whose provider returns a list of connectable accounts — Messenger pages, Instagram-via-Facebook accounts, WhatsApp phone numbers — share one implementation instead of each building its own picker: apps/builder/src/features/channel-connect/ (ConnectSelectionForm + useConnectFlow + ConnectManyDialog + CoexistStep).

• Single-account server core + oRPC route — one plain server function per provider id (e.g. actions/connect-page.ts's connectMessengerPage), returning ConnectActionResult<TOutcome> ({ kind: "outcome", outcome } or { kind: "sessionError", code }) — never a thrown exception the client has to classify, and never a 500 (the route would be unclassifiable). Build the three outcome literals with lib/connect-action-outcomes.ts's notSelectableOutcome / duplicatedOutcome / connectedOutcome, wrap best-effort follow-ups (branding, tag scan, …) in runConnectFollowUps, and convert the core's outer catch with toConnectActionFailure. Expose it as POST /api/channels/<channel>/connect from the feature's api/ folder (authorizedAPI, ids-only input, registered through the feature's api/index.ts) — not a server action: Next serializes server actions from one browser, so the picker's batch could only connect one account at a time. Add a server action only for a form that genuinely needs one (as WhatsApp's top-level connect form does), delegating to the same core.
• resolveConnectSession (lib/resolve-connect-session.ts) — reads the pending-auth cookie or signup session for both legs (initial provider list fetch and the per-id connect call); returns the same session-error codes the outcome wire type carries.
• Client side — every picker posts through lib/connect-client.ts's connectViaApi (path from CONNECT_CHANNEL_REGISTRY[channel].connectPath), which turns any transport failure into the batch's own failed/unknown outcome. useConnectFlow runs a single pick inline (button spinner) and fans 2+ picks out through ConnectManyDialog's status list, CONNECT_CONCURRENCY at a time. On a coexist-eligible channel (isCoexistChannel, packages/utils/channel.ts) the "sync existing history" opt-in is a per-row switch in the picker (CoexistRowSwitch / CoexistOptionsPanel), not a step: each row's call runs right after that row connects, via lib/coexist-client.ts's setCoexist (useConnectBatch's afterConnect for a batch, inline in useConnectFlow for a single pick). A channel with its own picker form gets the same rule by calling hooks/use-coexist-selection.tsx's useCoexistSelection — don't re-derive coexistIds ⊆ selectedIds by hand. The dialog's Continue skips every channel extra step on the session errors in SESSION_ERRORS_SKIPPING_EXTRA_STEPS (lib/row-status.ts), whose routes workspaceAuthorizedMidddleware would deny anyway. CoexistStep/CoexistPopup survive only for WhatsApp's manual/auto-select direct path.
• New channel registration — add one entry to lib/registry.ts's CONNECT_CHANNEL_REGISTRY, typed satisfies Record<ConnectPickerChannel, ConnectChannelConfig> so a missing channel fails to compile. That file is the only place in channel-connect allowed to hard-code a channel name.
• Row/warning copy — lib/row-status.ts (ROW_STATUS, REASON_MESSAGE_KEYS, WARNING_MESSAGE_KEYS, SESSION_ERROR_MESSAGE_KEYS) is the single source of i18n keys for every row state, failure reason, and outcome warning shown in the dialog — reuse these, don't add a channel-local copy of the same labels.

Existing Integrations Reference

Channel vs integration. Not every integration is a channel. channelTypes (packages/utils/src/channel.ts:18) is exactly: omnichannel, webchat, messenger, whatsapp, zalo, smtp, telegram, instagram, tiktok, api. Entries below that are not in that list (google-sheets, instagram-facebook, …) are integrationTypes only — they connect an external service but carry no inbox conversation.