botpress api 'conversation not found'

TL;DR

Botpress conversations live inside one bot. 'Conversation not found' means the id doesn't exist there: it's from a different bot, a different environment, or it was deleted. Conversation ids are not portable across bots or environments. Fetch the conversation list for the bot you're actually calling and use an id from it.

The query

botpress api 'conversation not found'

Use this when

• Botpress API calls fail with 'conversation not found'
• Conversation ids from webhooks don't resolve in API calls
• Ids work in staging but not in production

Not for

• Botpress API authentication errors
• Messages failing to deliver to existing conversations
• Botpress Studio editing or publishing issues

Steps

1. List conversations on the bot you're calling

Call the conversation list endpoint against the exact bot id in your API call. If your id isn't in the list, it doesn't exist there. This takes thirty seconds and settles most cases.

Expected output: the conversation list for the bot, with or without your id in it.

2. Check for bot id mismatch

The classic cause: the webhook came from bot A and your code queries bot B. Compare the bot id in the webhook payload with the bot id in your API call. Dev and prod bots have different ids.

Expected output: matching bot ids in the webhook payload and your API call.

3. Check environment separation

Staging conversations don't exist in production and vice versa. If the id came from a staging test, it's simply not in prod. Use ids generated in the same environment you're querying.

Expected output: the id confirmed as created in the environment being queried.

4. Handle deleted and expired conversations

If the id used to work, the conversation may have been deleted or aged out by retention policy. Treat this as expected for old ids: create a new conversation instead of failing the flow.

Expected output: graceful handling that starts a new conversation for missing ids.

Variant phrasings

botpress conversation id invalid

Steps 1 and 2 cover existence and bot mismatch.

botpress get conversation 404

Step 3 for environment mixups, step 4 for aged-out conversations.

Why it happens

Botpress scopes everything to the bot: users, conversations, and messages all hang off a bot id. Integrations tend to store conversation ids durably but forget which bot and environment produced them. Months later the id is a fossil from a deleted staging bot, and the API correctly reports it missing.

Edge cases

• Conversation ids in logs without the bot id are undebuggable. Log both together.
• Bot duplication (clone for a new client) doesn't carry conversations. Expect empty lists on clones.
• Retention policies delete old conversations silently. Check the policy before assuming a bug.

Provenance

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