Channel Integrations

Connect external channels to the inbox: Facebook, Instagram, mail, Discord, Call, and Call Pro, plus the integration lifecycle and webhook routes.

Backend: backend/plugins/frontline_api/src/modules/integrations/<kind>/ holds one runtime per kind; integrations/trpc is the in-plugin tRPC router. Frontend: frontend/plugins/frontline_ui/src/modules/{integrations,integrations-config}.

Concepts

Integration kinds

Every Integration record has a kind. inbox.getIntegrationKinds (modules/inbox/utils.ts) returns the registered map: messenger (Messenger), lead (Popups & forms), webhook (Webhook, a generic inbound webhook with an auto-generated token), booking, callpro (Callpro), mail (Email), facebook-messenger, facebook-post, instagram-messenger, instagram-post, discord-messenger (Discord), calls (Phone call), client (Client Portal), and vendor (Vendor Portal). Creation code also accepts cloudflarecalls as a service kind.

An integration is always attached to one channel. integrationsCreateExternalIntegration refuses channelId values that point at another user's personal channel; when no channelId is given, the integration lands in the connecting user's own personal channel.

Lifecycle operations

Mutations live in resolvers/mutations/integrations.ts.

Queries: integrations, integrationDetail, allLeadIntegrations, integrationsGetUsedTypes, integrationsGetUsedTypesByChannel, integrationGetLineWebhookUrl, integrationsTotalCount, and integrationsGetMessengerColorThemes, plus per-kind lists.

Webhook routes

src/routes.ts mounts routers on the plugin's Express app:

Inbound payloads flow into receiveInboxMessage, which creates/reuses the customer, conversation, and message and publishes conversationClientMessageInserted.

Facebook and Instagram (Meta)

App credentials come from getConfig: per-workspace config records first, environment variables as fallback; environment-only when VERSION=saas.

The facebook/instagram modules store per-integration tokens and page/account state, mirror comments/messages into conversations, and expose GraphQL login/reply/account helpers. Facebook and Instagram automation triggers/actions (e.g., comment events) are registered from meta/automations, and the Facebook comment outbox worker starts at plugin init (main.ts).

Mail

Inbound and outbound mail run through Cloudflare.

1. A Cloudflare Email Routing worker posts inbound email to POST /mail/receive on this API, signed with MAIL_WEBHOOK_SECRET (HMAC). MAIL_RECEIVE_URL, MAIL_WORKER_URL, and MAIL_TENANT configure the worker side.
2. Mail messages thread onto conversations by mailData/References/In-Reply-To headers; each mail integration maps to one inbox channel.
3. Outbound mail uses Cloudflare Email Sending. A workspace connects its own Cloudflare account (mailCloudflareConnect, mailCloudflareProvision, mailCloudflareDisconnect); without one, the deployment's fallback account (MAIL_DOMAIN, MAIL_SENDING_ACCOUNT_ID, MAIL_SENDING_API_TOKEN, MAIL_SENDING_DAILY_LIMIT) is used.
4. mailPipelineIntegration/mailPipelineConnect/mailPipelineUpdate/mailPipelineForwardVerified/mailPipelineDisconnect route mail into pipelines; mailSendMail, mailMessageRetry, mailConversationDetail, mailSendingReadiness, mailCloudflareConnection, mailCloudflareSendingQuota, mailCloudflareZones, mailCheckConnection cover sending, retry, and diagnostics.

Discord

initDiscord() runs at plugin startup (main.ts) and opens a Discord gateway client per configured integration; guild messages become conversations and agent replies post back through the Discord API. Discord automation entries are registered in meta/automations.

Call (SIP/CDR)

The call module stores CallCdrs and integrates a SIP provider via CALL_ENDPOINT_URL. CALL_WEBHOOK_REQUIRE_SIGNATURE=true enforces signed webhooks; CALL_SUBSCRIPTION_REQUIRE_AUTH=true requires auth on the call GraphQL subscription. CDR records join inbox search by phone number and feed the call report services.

Call Pro (webhook PBX)

Call Pro is gated per tenant (the subdomain a request belongs to):

• CALLPRO_ENABLED=true turns the module on; CALLPRO_SUBDOMAINS is a comma-separated tenant allowlist on shared deployments.
• Tenants outside the allowlist get a disabled config, a 404 from /callpro/receive, and rejected create/update operations.
• POST /callpro/receive ingests PBX call events, which appear as conversations/CDR entries and feed call reports.

Bot automations

Conversation automation is coordinated through automatedReplyControl on each conversation (status, reason, pausedUntil) and the conversationSetAutomatedReplyControl mutation. A bot sets handoff_requested; an agent accepts with human_active. The automationStatus inbox filter exposes these states (standby, handoff, responded).

Environment variables