Connect a support-conversation channel (Chatwoot / Intercom)

SupaCloud can act as the AI-resolution backend behind Chatwoot and Intercom. An inbound customer message is HMAC-verified, enqueued as a gated backlog item, and worked by an agent that reads and replies through governed conversation.* tools — one ConversationProvider seam, two transport adapters.

Note

The conversation feature is edition-gated by the support_channels entitlement. On a self-hosted Enterprise-edition instance it is granted instance-wide; on the SaaS plans it is on the paid tiers. If resource creation is refused with a plan error, your plan does not include support channels.

Prerequisites

• A Chatwoot account (self-hosted or cloud) with an agent-bot access token, or an Intercom workspace with a workspace access token.
• For Chatwoot: the instance base URL + the numeric account_id. For Intercom: the region (us / eu / au) + the bot admin_id.
• The webhook signing secret each platform will sign deliveries with (the Chatwoot inbox HMAC secret / the Intercom app client_secret).
• A workspace where you can create resources and a workflow.

Steps

1. Create the channel resource.

   In Resources → New, pick Chatwoot or Intercom.

   • Chatwoot — set base_url (e.g. https://chat.example.com) and account_id; paste the agent-bot access token as the secret. Because a self-hosted host is operator-supplied, every outbound call to it goes through SupaCloud’s SSRF-pinned client.
   • Intercom — choose the region and set the bot admin_id; paste the workspace access token as the secret. Intercom’s regional API host is a fixed allowlist, so no host needs SSRF-pinning.

2. Add an inbound conversation trigger.

   On the workflow that should handle conversations, add a trigger of kind chatwoot_conversation or intercom_conversation. Configure:

   • resource_id — the channel resource from step 1 (auto-bound when the workspace has exactly one of that kind).
   • signing_secret — the webhook HMAC secret the platform signs with.
   • mode — auto-reply (agent answers autonomously, under your autonomy / budget gates), human-gate (answer held for human approval), or notify-only (verified deliveries are acked but start no agent work).

   The trigger cannot be enabled until both a resource_id and a signing_secret are present. Copy its receiver URL from the workflow’s Triggers panel.

3. Wire the platform webhook.

   Point the platform at the trigger’s receiver URL:

   • Chatwoot (Settings → Integrations → Webhooks): subscribe to Conversation Created + Message Created, set the HMAC secret to your signing_secret. SupaCloud verifies X-Chatwoot-Signature = HMAC-SHA256 over {X-Chatwoot-Timestamp}.{body}, with a stale-timestamp replay guard.

     POST <server public_url>/api/workflows/triggers/chatwoot/<token>

   • Intercom (Developer Hub → Webhooks): subscribe to conversation.user.created + conversation.user.replied, set the trigger’s signing_secret to your app’s client_secret. SupaCloud verifies X-Hub-Signature = HMAC-SHA1 over the raw body.

     POST <server public_url>/api/workflows/triggers/intercom/<token>

   Caution

   The signing secret is per-trigger and authenticates every delivery. A delivery with a missing or bad signature is rejected (401); an unknown token returns a uniform 404. A verified but non-actionable delivery (an outgoing / agent message, an unsubscribed event, or a stale replay) is acked with 200 and started no work.

4. Let the agent resolve conversations.

   A verified new conversation / incoming customer message is enqueued as a backlog item and dispatched under the same autonomy, budget and quiet-hours gates as any other work. The agent reads and acts on the conversation through the conversation.* MCP tools: conversation.get / conversation.list (read), and conversation.reply / assign / resolve / handoff (ops). A customer-visible reply rides the same SSRF-vetted sender; handoff is the explicit escape hatch back to a human team.

See also

• Connect a Discord bot
• Operate the delivery engine