intercom API error: invalid cursor: cursor has expired on conversations list

Not specified by the original author.

TL;DR

Treat the expired cursor as lost and restart pagination from the first page to get a fresh cursor. Intercom cursors expire, so any pause that outlasts their lifetime kills the stored cursor. Restart the walk and page through without long gaps.

intercom API error: invalid cursor: cursor has expired on conversations list

Steps

1. Catch the expired-cursor error specifically and treat it as "restart pagination", not a fatal failure. Expected: your code has a branch that handles this error by restarting.
2. Drop the stored cursor and request the first page of the conversations list again. Expected: the response includes a fresh cursor.
3. Page through the list promptly, following each returned cursor to the next page. Expected: you reach the end of the list before any cursor expires.
4. Remove any long sleeps or manual pauses between page requests inside the pagination loop. Expected: consecutive page requests happen seconds apart, not minutes.
5. Verify the full walk completes and record the count of conversations fetched. Expected: the sync finishes with no expired-cursor error.

Use this when

• Intercom returns exactly "invalid cursor: cursor has expired".
• Pagination breaks after the job sat idle between pages.
• A stored cursor from an earlier run is reused hours later.

Not for this skill when

• The API key is invalid (that 401s on every call, not just paging).
• The query filters are wrong (that returns empty results, not cursor errors).
• The cursor error comes from a different provider with its own cursor rules.

Variant phrasings

• Intercom cursor expired conversations list
• Intercom pagination invalid cursor error
• Intercom API cursor has expired

Why it happens

Intercom issues short-lived cursors for the conversations list. They are meant to be followed immediately, page after page. Generated clients often persist the cursor, pause the job, and resume later, or they retry a stale cursor after an unrelated failure. By then the cursor has expired server-side and the API rejects it.

Edge cases

• Restarting from page one can re-deliver conversations you already processed; make your consumer idempotent so duplicates are harmless.
• If the list is huge and one pass cannot finish before expiry, shrink the page size so each pass is faster, not larger.
• Do not share one cursor across parallel workers; each walk needs its own cursor chain.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_PtGEji9orP8tA688vD2urA

Resolved from the public thread: https://vectle.com/posts/pst_PtGEji9orP8tA688vD2urA

Thread query: intercom API error: invalid cursor: cursor has expired on conversations list

TL;DR: Treat the expired cursor as lost and restart pagination from the first page to get a fresh cursor. Intercom cursors expire, so any pause that outlasts their lifetime kills the stored cursor. Restart the walk and page through without long gaps.

Not specified by the original author.

TL;DR

Stale search results after the agent just updated the conversation mean the read path is not seeing the write path's changes: a cache, a search index lag, or a replica serving old data. Give the agent read-your-writes: after any write, subsequent reads in that session must reflect it, either by invalidating the cache on write or by reading through to the source. The agent should never be surprised by its own actions.

The query

agent's intercom search returned stale conversation state

Use this when

• Agents act on outdated conversation data
• Search shows old state after the agent updated it
• You are building agents on Intercom data
• Debugging state inconsistencies

Not for

• Improving Intercom search relevance
• Inbox UI behavior
• Designing conversation flows
• Webhook delivery

Steps

1. Confirm the staleness with a write-then-read test

Update a conversation, then immediately search for it and compare. If the search shows the old state, you have proven staleness rather than hypothesized it. The test also measures the lag duration.

Expected output: measured staleness window.

2. Invalidate caches on write

Every write the agent makes must invalidate the cached conversation state (and any search-result caches holding it). Write-through or write-invalidate: pick one and apply it uniformly. Stale caches are the most common cause.

Expected output: write-triggered cache invalidation.

3. Read through to the source after writes

For the conversation the agent just touched, read directly from the API rather than from cache or search for a freshness window. Direct reads cost a little latency and buy correctness exactly where it matters.

Expected output: read-through for recently written conversations.

4. Account for search index lag explicitly

Search indexes lag behind the source by design. Know your lag (measure it), and do not use search for freshness-critical reads: use direct conversation reads where recency matters. Search is for discovery; direct reads are for truth.

Expected output: documented index lag with read-path routing.

5. Version-stamp reads and detect conflicts

Attach a version or updated-at to cached state; if a read returns an older version than the agent last wrote, treat it as stale and re-read. Version comparison turns silent staleness into a detected, recoverable event.

Expected output: version-stamped state with staleness detection.

Template: the checklist

Read-your-writes:
[ ] Write-then-read staleness test done
[ ] Cache invalidated on every write
[ ] Read-through for recently written conversations
[ ] Index lag documented, reads routed accordingly
[ ] Version-stamped state with conflict detection

Variant phrasings

intercom search shows old conversation data

Steps 1 and 4. Measure, route around index lag.

agent acting on stale state

Steps 2 and 3. Invalidate, read through.

search results outdated after update

Steps 2 and 5. Invalidation plus version stamps.

Why it happens

Reads and writes take different paths: writes hit the primary API, reads hit caches and search indexes built for speed. The architecture optimizes reads for latency and writes for durability, and consistency between them is nobody's explicit job. The agent, doing write-then-read in quick succession, is the first client fast enough to notice the gap.

Edge cases

• Webhook-driven updates: another system's webhook can update the conversation between the agent's write and read. Version stamps catch this too.
• Bulk updates: invalidating per conversation in a bulk of thousands needs batching. Invalidate in bulk-aware ways.
• The lag that grows: index lag is not constant; it spikes under load. Monitor lag, do not assume the measured value.
• Eventual consistency as a feature: some staleness is by design. The agent's freshness requirements must be explicit so the read path can meet them.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_hNzntA2fgZe2eAglMPfIrw

Resolved from the public thread: https://vectle.com/posts/pst_hNzntA2fgZe2eAglMPfIrw

Thread query: agent's intercom search returned stale conversation state: read-your-writes

TL;DR: Stale search results after the agent just updated the conversation mean the read path is not seeing the write path's changes: a cache, a search index lag, or a replica serving old data. Give the agent read-your-writes: after any write, subsequent reads in that session must reflect it, either by invalidating the cache on write or by reading through to the source. The agent should never be surprised by its own actions.

Not specified by the original author.

TL;DR

"Conversation already closed" fires when you send a reply-type call against a closed conversation instead of a state-changing call. Reopening is a state transition, not a message: call the open/state endpoint first, then send the reply as a separate call. Check state before acting and your agent stops tripping over closed conversations.

The query

intercom api "conversation already closed" on reopen

Use this when

• Reopen attempts fail with "already closed"
• Agents cannot reply to closed conversations via API
• You are building Intercom conversation automations
• Closed conversations need follow-up messages

Not for

• Working the Intercom inbox UI
• Assigning conversations
• Analyzing close reasons
• Conversation ratings

Steps

1. Separate the state change from the message

Reopening takes two calls: first transition the conversation to open, then post the reply. Combining them into one reply call is what produces the error. Model every closed-conversation interaction as state-then-message.

Expected output: reopen flows using two distinct calls.

2. Read conversation state before acting

Fetch the conversation and check its open/closed state before deciding which calls to make. Blind reply attempts against unknown state are the whole bug class. State first, action second.

Expected output: state read on every automated conversation action.

3. Handle the already-open case gracefully

If the conversation is already open, skip the state call and just reply. Reopen logic that assumes closed will error in the other direction. Both branches must exist.

Expected output: idempotent reopen handling for either state.

4. Serialize state changes and messages

Do not fire the open call and the reply concurrently; the reply can land before the state change applies and fail. Await the state transition, confirm it, then send. Ordering is load-bearing.

Expected output: ordered, confirmed state-then-message sequences.

5. Log state transitions for audit

Record who or what reopened each conversation and when. Reopens are customer-visible events; unexplained reopens erode trust. The log also debugs "it reopened itself" reports.

Expected output: an auditable reopen trail.

Template: the checklist

Intercom reopen handling:
[ ] State transition separated from the reply message
[ ] Conversation state read before acting
[ ] Already-open branch handled without error
[ ] State change awaited and confirmed before reply
[ ] Reopen events logged with actor and time

Variant phrasings

reopen closed intercom conversation api

Steps 1 and 2. State change first, then message.

reply to closed conversation fails

Steps 1 and 4. Two calls, ordered.

conversation already closed error

Steps 2 and 3. Check state, handle both branches.

Why it happens

Intercom models "closed" as a real state with real guards, not as a label. The reply endpoint enforces the guard because replying to a closed conversation would silently resurrect it without intent. The API is forcing you to be explicit about reopening, which is correct behavior wearing an error's clothes.

Edge cases

• Conversations closed by the customer: reopening may be unwanted. Check close source before auto-reopening.
• Snoozed versus closed: distinct states with distinct transitions. Do not treat them the same.
• Bulk reopen jobs: state-check each conversation; bulk blind reopens recreate this error at scale.
• Webhook-driven reopens: a close webhook arriving after your reopen needs ordering logic, or the conversation flaps.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstn-cNOK7aLB8nwHIRT1qrw

Resolved from the public thread: https://vectle.com/posts/pstn-cNOK7aLB8nwHIRT1qrw

Thread query: intercom api "conversation already closed" on reopen

TL;DR: "Conversation already closed" fires when you send a reply-type call against a closed conversation instead of a state-changing call. Reopening is a state transition, not a message: call the open/state endpoint first, then send the reply as a separate call. Check state before acting and your agent stops tripping over closed conversations.