Intercom ↔ RingCX · Live hand-off runbook

Bridge Hand-off Runbook

Walkthrough for the live session with Nilesh / DevOps / Zach / John: the real state of the Intercom ↔ RingCX (Engage Digital) bridge, what's confirmed with real calls, how it becomes yours to run and maintain, and what's fully on your side.

Real product: RingCX · Engage Digital Protocol: Channel SDK Signing: HMAC-SHA512 Status: 3/3 directions tested with real calls

Key correction — cover this first

The original assumption was RingEX/MVP (OAuth Client ID/Secret). The real product is RingCX → Engage Digital, with its own request/response protocol (Channel SDK) — not a simple "notify and move on" webhook. Any doc or env var based on RingEX/OAuth/Validation-Token no longer applies.

Walkthrough — in meeting order

01 · Concept What the bridge is ▸

A service that sits between Intercom and RingCX. When Fin escalates to a human, the bridge translates messages between both systems so the customer sees one continuous conversation.

02 · Protocol How the Channel SDK works ▸

RingCX doesn't passively notify: it asks, and our backend has to answer on the spot in the exact shape it expects.

Exchange	Direction	What our backend does
`implementation.info`	RingCX → us	Declares supported objects/actions (messages, threads · create, show, list, reply). Fires when the channel config is saved, then roughly every ~1 min on its own.
`messages.create`	RingCX → us	Agent replied in RingCX → forward to Intercom → respond with `{id, body}`.
`.list` / `.show`	RingCX → us	Sync request. "Real Time only" mode → we respond `[]` / `{}`.
Send API	us → RingCX	POST with `action: messages.create` and `author` = customer (avoids the `cant_reply_to_agent` error from the old REST API, now abandoned).

03 · Security HMAC-SHA512, not what we first assumed ▸

Channel	Mechanism
Intercom → bridge	HMAC-SHA1 · `INTERCOM_CLIENT_SECRET` · header `X-Hub-Signature`
Intercom Workflow → bridge (`/internal/escalate`)	Shared secret · `INTERNAL_HANDOFF_SECRET`
RingCX ↔ bridge (Channel SDK, both directions)	HMAC-SHA512 · `RINGCENTRAL_ENGAGE_SOURCE_SECRET` · header `X-SMCCSDK-SIGNATURE`

04 · Persistence DynamoDB, single-table ▸

pk	Content	Purpose
`conv:<intercom_conversation_id>`	`{ ringcentral_thread_id }`	New customer message in Intercom → which RingCX thread to forward it to
`rc:<ringcx_thread_id>`	`{ intercom_conversation_id }`	Agent replied in RingCX → which Intercom conversation to inject it into
`evt:<intercom_event_id>`	`{ ttl }`	Duplicate protection for Intercom webhook retries (24h TTL)

Runs on DynamoDB Local for dev (Matías's machine) and points to real DynamoDB on AWS just by changing env vars — no code changes needed.

05 · Finding We generate the thread_id ourselves ▸

Confirmed with real tests: we generate the thread_id with crypto.randomUUID(), send it to RingCX as if it already existed, and RingCX creates it automatically the first time it sees it. No need to parse any ID out of RingCX's response. This significantly simplified escalation.js.

06 · Puppetizable identity What's 100% on Unicity's side ▸

We already created the escalateops-bridge-bot identity with users.create and puppetizable: true. For a real agent to reply, John / Unicity needs to do this in their admin panel:

Digital → Identities → mark that identity as "controlled."
Assign it to whichever agent(s) will be replying.
Confirm read + reply permissions for those agents on this channel.
Confirm the channel is in the "real time" Channel Group (under Routing).

07 · Code hand-off How this becomes yours to run — not Matías's laptop ▸

Nothing gets "transferred running." Unicity rebuilds the exact same thing on its own infrastructure, following this repo plus the checklist below — from that point on, Matías is no longer a dependency for keeping it alive.

Package the code — server.js, the full src/ folder, package.json, package-lock.json, the Dockerfile, and this documentation. Skip node_modules (rebuilt with npm install) and skip .env — never shared as a file. The local test-*.js scripts are dev-only and optional to include.
Hand it over — as a zip, or better, a private GitHub repo so the integration keeps getting versioned as it evolves.
Secrets travel separately — never in the same package as the code, never pasted in Slack. A quick call or a shared password manager, landing directly in AWS Secrets Manager.
DynamoDB Local → real DynamoDB — the local database used for development isn't moved anywhere; Nilesh creates a brand-new, empty table in Unicity's own AWS account (command in the checklist below).
The server stops living on a laptop — Nilesh builds the included Dockerfile into an image and runs it on Unicity's own infrastructure (ECS/Fargate or equivalent), with its own permanent URL. No more ngrok.

Confirmed with real calls — not simulated

Customer writes in Intercom → lands as a real message in a RingCX thread (the email actually arrived) · Agent replies in RingCX → lands in the real Intercom conversation with zero errors · Brand-new thread created from scratch with a self-generated ID · All 3 security layers working · Persistent store in DynamoDB with duplicate protection.

Hand-off checklist — walk through live

Business pending items 0 / 0 ▸

Test with a real human agent replying (blocked on the 4 identity steps — 100% on Unicity/John's side)
Test the real escalation trigger: Intercom's Workflow Data Connector calling /internal/escalate with a real conversation (not the manual curl test)
Deploy to AWS — currently running on Matías's computer + ngrok

One-time, first deploy 0 / 0 ▸

Receive the code hand-off (see pillar 07 above) — zip or private repo, secrets passed separately
Create the DynamoDB table on AWS
Enable native TTL on the ttl attribute
IAM role with GetItem/PutItem on that table only
Load the in-use secrets into AWS Secrets Manager — never a .env file copied to the server
Confirm NODE_ENV=production (disables debug routes)
Build the Docker image and deploy to ECS/Fargate with HTTPS + health check on GET /health
Update the RingCX channel's Base URI to the final production URL (not ngrok)

Technical reference

POST /internal/escalate — Fin escalation trigger

Header: Authorization (INTERNAL_HANDOFF_SECRET, stored as an Authentication Token in the Data Connector)
Action: escalation.js generates a new thread_id, creates the thread in RingCX, saves the mapping

Channel SDK RingCX webhook — implementation.info / *.list / *.show / messages.create

Verification: X-SMCCSDK-SIGNATURE (HMAC-SHA512)
Mode: Real Time only → *.list responds [], *.show responds {}

PENDING RingCX admin panel — 4 puppetizable identity steps

100% on John/Unicity's side — see pillar 06 above

Environment variables in use

Variable	Status
`INTERCOM_CLIENT_SECRET`	in use
`INTERCOM_ACCESS_TOKEN`	in use
`INTERNAL_HANDOFF_SECRET`	in use
`RINGCENTRAL_ENGAGE_SEND_URL`	in use — Send API URL, includes source_id
`RINGCENTRAL_ENGAGE_SOURCE_SECRET`	in use — HMAC-SHA512 signing
`RINGCENTRAL_VERIFICATION_TOKEN`, `CLIENT_ID/SECRET`, `JWT`, `API_TOKEN`, `SERVER_URL`, `SOURCE_ID`, `AUTHOR_ID`	dead — delete in cleanup — leftovers from RingEX/OAuth and the abandoned REST API

Blockers — who they depend on

Real human agent replying — 100% depends on Unicity/John completing the 4 puppetizable-identity steps (section 06). Without this, a real agent can't reply even though the infrastructure is already tested.
AWS deploy — not started yet. No pending code work, purely DevOps/Nilesh following the checklist above.
End-to-end test of the real escalation trigger — mechanism proven separately (Data Connector reaches us fine, escalation.js creates threads fine); still needs testing together with a real conversation.