@crvouga/mockingbird-service-intercom

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of the Intercom REST API (version 2.11) for test suites. It serves the calls our backend makes:

• contacts: search, create (409 on duplicates, the way Intercom does), update and get;
• conversations: create (optional Idempotency-Key), update, reply as the member or as an admin (JSON or multipart attachments), close/open/snooze/assign, get with ?display_as=plaintext, and cursor-paginated search;
• identity: /admins and /me.

Admin replies and close/open (and, for a receiver that subscribes to them, member messages and replies) send Intercom's notification_event webhooks, signed with X-Hub-Signature: sha1=<hex HMAC-SHA1>, to both of our receivers: the backend's POST /messaging/webhook and the EMR's POST /v1/webhooks/intercom.

• Operation coverage: SUPPORT.md
• The contract (openapi.yaml) is trimmed from Intercom's published 2.11 reference to what our consumers use.

Install

npm install -D @crvouga/mockingbird-service-intercom

ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with npx mockingbird-intercom serve, createServer from ./server (Node), or createRuntime with any Fetch server.

Usage

npx mockingbird-intercom serve --port 8807 \
  --webhook-url http://127.0.0.1:3000/messaging/webhook \
  --emr-webhook-url http://127.0.0.1:4000/v1/webhooks/intercom \
  --webhook-secret "$INTERCOM_WEBHOOK_SECRET"

Add --webhook-events conversation.user.created,conversation.user.replied,conversation.admin.replied,conversation.admin.closed,conversation.admin.opened to subscribe --webhook-url to the member topics too; --emr-webhook-url keeps the admin-only default.

import { IntercomClient } from "intercom-client"
import { createServer } from "@crvouga/mockingbird-service-intercom/server"

const emulator = await createServer({
  webhooks: {
    urls: ["http://127.0.0.1:3000/messaging/webhook", "http://127.0.0.1:4000/v1/webhooks/intercom"],
    secret: "whsec-test",
  },
})

// The application's Intercom client. Only baseUrl changes.
const intercom = new IntercomClient({ token: "any-token", baseUrl: emulator.url })
const contact = await intercom.contacts.create({ role: "user", external_id: "1652", email: "[email protected]" })
// The member opens a conversation through the app.
const message = await intercom.conversations.create({
  from: { type: "user", id: contact.id ?? "" },
  body: "Are my results in?",
})

// Test control. Support answers: appends an admin comment and fires the signed conversation.admin.replied.
await fetch(`${emulator.url}/__admin/conversations/${message.conversation_id}/admin-reply`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ adminId: "1000001", body: "Your results are in" }),
})

await emulator.close()

Routes

Every route needs Authorization: Bearer <token>. Any non-empty token is accepted unless tokens is set. Intercom-Version defaults to 2.11, and a malformed value answers 400 intercom_version_invalid. Every error uses Intercom's envelope: {type: "error.list", request_id, errors: [{code, message}]}.

Conversation state follows Intercom:

• Admin comments set read: false, meaning unread for the member.
• Member replies set read: true, set waiting_since, and reopen a closed or snoozed conversation.
• PUT {read: true} marks the conversation read.
• Notes change nothing the member sees.
• Bodies are stored as HTML. Plain text is wrapped in <p>, one paragraph per line, and display_as=plaintext turns it back into text.

Attachments keep their metadata only: name, content type, size, and a downloads.intercomcdn.com URL that is not served. The uploaded bytes are never stored.

Search

A query is either a filter {field, operator, value} or a compound {operator: "AND" | "OR", value: [query, …]}, nested up to two levels.

• Operators: =, !=, IN, NIN (these two take an array), <, >, ~ (contains), !~, ^ (starts with) and $ (ends with). String comparisons are case-insensitive.
• Contact fields: id, external_id, email, name, phone, role, the timestamps, and custom_attributes.<name>.
• Conversation fields: id, contact_ids, teammate_ids, admin_assignee_id, team_assignee_id, state, open, read, priority, title, the timestamps, and source.{id,type,delivered_as,subject,body,author.id,author.type,author.name,author.email}.
• Unknown fields or operators answer 400 parameter_invalid.
• Sorting: updated_at descending by default, with the id as tiebreaker.
• Cursors: opaque base64, 20 per page by default.

Webhooks

The emulator sends webhooks for these events:

An endpoint receives the four admin topics above unless it lists its own events. The member topics, conversation.admin.snoozed and .assigned are published but opt-in: subscribe with --webhook-events, webhooks.urls: [{url, events}] or PUT /__admin/webhook-endpoints. The EMR treats every notification_event it receives as an admin event, so its subscription must not include member topics. Notes send nothing.

Each delivery is a JSON body posted with X-Hub-Signature: sha1=<hex HMAC-SHA1(secret, rawBody)>:

{ "type": "notification_event", "app_id": "mockapp", "topic": "conversation.admin.replied",
  "id": "notif_…", "created_at": 1760000000, "delivery_status": "pending", "delivery_attempts": 1,
  "data": { "type": "notification_event_data", "item": { "type": "conversation", "id": "…",
    "source": { "delivered_as": "customer_initiated", "author": { "email": "…" }, "body": "…" },
    "contacts": { "contacts": [{ "id": "…", "external_id": "1652" }] },
    "conversation_parts": { "conversation_parts": [ { "id": "…", "part_type": "comment", "body": "<p>…</p>", "created_at": 1760000000 } ] } } } }

• Only the new part. item.conversation_parts holds just the part that caused the event, as in Intercom's own payloads.
• Wall-clock timestamps. The part's timestamps and the envelope's created_at use real time, never the emulator clock, because the EMR rejects parts more than 5 minutes old against its own clock.
• Stable id. The notification id stays the same on retries and on webhook_duplicate, so the backend's delivery_id ?? id dedupe and the EMR's processed-marker dedupe both hold.
• Retries. A non-2xx answer is retried after 5 s, 5 min, 30 min and 2 h.
• Admin plane. GET /__admin/webhooks, …/events, …/flush, …/:id/replay and PUT /__admin/webhook-endpoints are the standard webhook admin routes.

Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}):

Namespaces

• the x-mockingbird-namespace header;
• a /__admin/ns/<name> prefix on INTERCOM_API_BASE_URL;
• the access token: PUT /__admin/credentials {"credentials": {"<INTERCOM_ACCESS_TOKEN>": "<namespace>"}}.

The request journal records operation ids, statuses and contact, conversation and part ids. It never records message bodies or contact details.

Deliberately not modelled

• The member-app Messenger SDK and web widget (@intercom/intercom-react-native, @intercom/messenger-js-sdk). They talk to Intercom's own hosts over their own protocol. The web widget has no test-stage gate, so QA should block it.
• Attachment downloads: URLs are recorded but not served.
• Tags, notes, companies, segments, tickets, articles, data-attribute management, teams and SLAs. These appear only as empty lists where a payload has them.
• Rate-limit headers on normal responses. Only rate_limited sends them.
• Intercom's exact wording for the idempotency conflict, which is unverified: the emulator answers 409 conflict.

API

Part of mockingbird.