Intercom Debug Bundle Skill

Intercom Debug Bundle

Overview

Collect diagnostic evidence for Intercom issues: API health, auth status, rate-limit headers, SDK version, platform incidents, and redacted logs — packaged as a timestamped tarball safe to attach to a support ticket. Most persistent failures are auth (401) or rate-limit (429) problems, so the bundle leads with the /me health check before collecting anything heavier.

Prerequisites

Intercom access token exported as INTERCOM_ACCESS_TOKEN
curl and jq available
Access to application logs (optional — the collector redacts them)

Instructions

Step 1: Confirm auth before collecting

Most failed bundles are a bad token. Confirm /me returns 200 first; if not, fix auth before running the full collector.

TOKEN="${INTERCOM_ACCESS_TOKEN:?set INTERCOM_ACCESS_TOKEN and re-run}"
curl -s -o /dev/null -w "Auth HTTP: %{http_code}\n" \
  -H "Authorization: Bearer $TOKEN" \
  https://api.intercom.io/me
# 200 = OK, 401 = regenerate the token in the Developer Hub

Step 2: Run the full bundle collector

When the quick check passes, run the seven-step collector. It writes token status, auth JSON, rate-limit headers, platform status and active incidents, environment/SDK info, endpoint latencies, and redacted logs into a timestamped directory, then tars it up as intercom-debug-YYYYMMDD-HHMMSS.tar.gz. Tokens, emails, and .env values are stripped before packaging.

See the complete intercom-debug-bundle.sh script (all seven steps) in full implementation.

Step 3: Redact and review before sharing

The collector redacts as it goes, but review the tarball before attaching it to a ticket. What to ALWAYS redact vs what is SAFE TO INCLUDE (with copy-paste curl snippets for reading rate-limit headers and capturing a request_id) lives in examples and redaction rules.

Output

intercom-debug-YYYYMMDD-HHMMSS.tar.gz containing:
- summary.txt — token status, auth result, rate-limit headers, platform status, active incident count, environment, SDK version, and per-endpoint latency (/me, /contacts, /conversations, /admins)
- logs-redacted.txt — recent Intercom-related log lines with tokens and emails masked (present only if logs/app.log exists)
- config-redacted.txt — .env copy with all values masked (present only if .env exists)

Sensitive Data Policy

ALWAYS redact: access tokens, OAuth secrets, webhook signing secrets, email addresses and PII, customer conversation content.

Safe to include: HTTP status/error codes, request_id from error responses (Intercom support needs these), rate-limit header values, SDK/runtime versions, endpoint latencies. Full rules in examples and redaction rules.

Error Handling

| Issue | Cause | Solution | |-------|-------|----------| | jq: command not found | jq not installed | apt install jq or brew install jq | | Auth test returns 401 | Token invalid | Regenerate in Developer Hub | | Status page unreachable | Network issue | Try curl https://status.intercom.com directly | | No rate limit headers | Request failed early | Fix auth first |

Examples

Quick reference for the most common check — confirm the token authenticates:

curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \
  https://api.intercom.io/me
# 200 = OK, 401 = regenerate token

For reading rate-limit headers, capturing a request_id from an error response, and the full redaction rules, see examples and redaction rules.

Resources

Intercom Status — real-time platform health and incidents
Intercom Support — help center and ticket submission
Error Codes Reference — full REST API error code list

Next Steps

For rate limit handling, see intercom-rate-limits. For auth setup, see intercom-install-auth.

Agent Skills: Intercom Debug Bundle

Install this agent skill to your local

Skill Files