Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/intercom-cost-tuning/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill intercom-cost-tuning. Copyright stays with the author (MIT).

Intercom Cost Tuning

Overview

Reduce Intercom API costs through smart caching, search optimization, webhook-driven architecture, and usage monitoring. Intercom pricing is primarily seat-based and feature-based, but API efficiency reduces infrastructure costs and avoids rate limits.

Intercom Pricing Model

Key insight: The API itself is free to use, but hitting rate limits (10K req/min) forces you to build queuing infrastructure. Reducing requests saves engineering time and infrastructure costs.

Prerequisites

• An Intercom workspace with an access token and the Node/TypeScript Intercom client installed.
• lru-cache available for the contact-caching step (npm install lru-cache).
• A public HTTPS endpoint to receive webhooks (Step 2) if you want to eliminate polling.
• Read access to the integration source so you can audit call sites: use Grep to find polling loops (setInterval, .list() and Read to inspect the surrounding call site before refactoring.

Instructions

Work top-down — Steps 2-4 remove the most requests for the least code; Steps 1 and 6 confirm and protect the gains. Full copy-paste code for every step is in references/implementation.md.

1. Audit current API usage. Instrument every call with an IntercomUsageTracker that counts calls and average latency per endpoint, then prints a rate estimate against the 10K req/min limit. You cannot cut what you have not measured.

2. Replace polling with webhooks. A 30-second poll loop costs ~2,880 requests/day per check; a webhook subscription costs zero and fires instantly:

   app.post("/webhooks/intercom", (req, res) => {
     const n = req.body;
     if (n.topic === "conversation.user.created") handleNewConversation(n.data.item);
     res.status(200).json({ received: true });
   });

3. Cache contact lookups. Wrap contacts.find in an LRU cache (10-min TTL) and invalidate entries on contact.updated webhooks so repeat reads never hit the API.

4. Use search instead of list + client filter. One contacts.search / conversations.search returns up to 150 filtered results in a single request instead of paging every record and filtering in memory.

5. Batch conversation lookups. Replace per-id find loops with a single filtered conversations.search.

6. Monitor request budget. A RequestBudgetMonitor warns at 80% of the limit and hard-stops at 95% to prevent 429 cascades.

Output

Applying this skill produces:

• A per-endpoint usage report (call counts, average latency, estimated req/min vs the 10K limit) from Step 1.
• A refactored integration where polling loops are replaced by webhook handlers, contact/conversation reads are cached or searched, and outbound calls pass through a budget guard.
• A measurable request-volume reduction — e.g. polling checks dropping from thousands of requests/day to zero, and list+filter queries collapsing from N pages to a single search request.
• Console warnings when request rate crosses 80% / 95% of the rate limit, replacing surprise 429 errors.

Cost Reduction Checklist

• Replace polling loops with webhooks
• Cache contact and conversation lookups (5-10 min TTL)
• Use search instead of list + client-side filter
• Batch related lookups into single search queries
• Track API request volume per endpoint
• Set up alerts at 80% rate limit usage
• Remove unnecessary API calls in hot paths

Error Handling

Examples

Worked, number-by-number scenarios are in references/examples.md:

• Kill a polling loop — 3 checks × 2,880 req/day → 0 via webhooks.
• Cache contact lookups — 50 find calls per inbox render → cache misses only.
• Search instead of list — 4,000-contact pro-plan query from 80 requests → 1.
• Budget guard under load — a bulk job self-paces below 10K req/min instead of taking a wall of 429s.

Resources

• Intercom Pricing
• Rate Limiting
• Search Contacts

Next Steps

For architecture patterns, see the intercom-reference-architecture skill in this pack, and drill into references/implementation.md for the full step-by-step code.