@kody/intercom

@kody/intercom — agent notes

Human setup and intent live in README.md. This file is for agents: imports, smoke/dryRun execute snippets, and edge cases. Secrets and OAuth by name only — never paste tokens. Do not disable live webhooks or jobs. The optional workspace-health job is disabled by default.

Auth

Hosts: api.intercom.io, api.eu.intercom.io, api.au.intercom.io. REST bases: US https://api.intercom.io, EU https://api.eu.intercom.io, AU https://api.au.intercom.io. Header: Intercom-Version: 2.14.

Do not hard-code a personal workspace id, admin id, or alias.

Import paths

Prefer static kody:@kody/intercom/... imports from execute. Do not lead with packages.invoke.

Smoke test (read-only)

import smokeTest from 'kody:@kody/intercom/smoke-test'

export default async function main() {
	return await smokeTest()
	// Without credentials: { ok: true, live: false } + connect / access-token URLs
	// With credentials: { live: true, hasAdminId } (no email)
}

Root dispatcher equivalent: import intercom from 'kody:@kody/intercom' then await intercom({ action: 'smoke-test' }).

Do not write live Intercom records from a smoke test.

dryRun / confirm

Mutating helpers require confirm: true. Pass dryRun: true to inspect the REST payload without calling Intercom. ./request treats GET and search POST as read-only; other POST / PUT / PATCH / DELETE need confirmation.

import createContact from 'kody:@kody/intercom/create-contact'
import replyConversation from 'kody:@kody/intercom/reply-conversation'

export default async function main() {
	const previewContact = await createContact({
		email: 'pat@example.com',
		name: 'Pat',
		dryRun: true,
	})
	const previewReply = await replyConversation({
		id: conversationIdFromCaller,
		body: 'Thanks — looking into this.',
		dryRun: true,
	})
	return { previewContact, previewReply }
}

Read helpers:

import listContacts from 'kody:@kody/intercom/list-contacts'
import listConversations from 'kody:@kody/intercom/list-conversations'
import listArticles from 'kody:@kody/intercom/list-articles'

export default async function main() {
	const contacts = await listContacts({ perPage: 10 })
	const conversations = await listConversations({ perPage: 10 })
	const articles = await listArticles({ perPage: 10 })
	return {
		contactCount: contacts.items.length,
		conversationCount: conversations.items.length,
		articleCount: articles.items.length,
	}
}

Unwrapped REST:

import request from 'kody:@kody/intercom/request'

export default async function main() {
	return await request({
		path: '/contacts',
		query: { per_page: 5 },
	})
}

Edge cases

• Search uses Intercom's query object, or email / state shortcuts.
• Reply and close resolve adminId from GET /me when omitted. Create article does the same for authorId.
• Helpers project slim records (id, role/state/title, timestamps). Use ./request when you need full conversation parts or article HTML.
• Prefer dedicated helpers over assembling ./request when one exists.
• ./scheduled-workspace-health only reads /me plus first-page counts; the workspace-health job stays disabled unless the owner enables it.