Intercom debug bundle

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.