Conversation Resume Identity Verification Automation: A Parameter That Was Documented and Ignored

Adding a field to an API's documented input type is the easy, visible half of building a feature — the type checker enforces that callers may pass it, and nothing enforces that the receiving code actually does anything with the value once it arrives. When the two halves drift apart, the result is not a crash or a visible error; it is a parameter that behaves exactly as if it were optional and ignorable, silently, for as long as nobody specifically checks whether the value made it all the way through to the logic that was supposed to consume it.

Centriu Synapse's public messaging endpoint accepts a `conversationId` field specifically so an integrator that already has an ongoing conversation with a customer can attach a new inbound message to that exact conversation, rather than the handler deciding on its own which conversation (or whether a new one) applies. Before this fix, the value arriving in that field was copied into `metadata.requestedConversationId` — and a direct search of the entire repository confirmed that specific field name appears in exactly one place: the line that writes it. Nothing downstream ever read it. The handler's actual conversation logic always ran its own, separate find-or-create-the-open-conversation path, completely independent of whatever conversationId the caller had explicitly asked for.

The practical consequence is a specific, quiet kind of data fragmentation: an integrator that believed it was continuing one particular conversation — because it deliberately supplied that conversation's own id — was, without any indication, having its message attached to whatever conversation the handler's own default logic happened to find or create instead. No error surfaced, because from the handler's point of view nothing had gone wrong; it had successfully done the thing it always does, just not the thing the caller had explicitly asked for.

The fix makes the parameter genuinely load-bearing, and does so carefully rather than naively. When `conversationId` is present, the handler now calls a dedicated resolution function that proves the requested conversation actually belongs to the calling API credential's own client before using it — checking that the conversation exists, that it belongs to the right tenant scope, that it belongs to the right customer record, and that it is not already closed. Only a conversation that passes every one of those checks is resumed exactly as requested; when the parameter is absent entirely, the historical find-or-create behavior is preserved unchanged, so existing integrations that never used the parameter see no change at all.

A request naming a conversation that fails any of those checks does not silently fall back to opening a different conversation — the specific failure that made the naive form of this fix newly risky. Instead, the handler raises a dedicated, typed error carrying an internal-only reason (not found, wrong tenant, wrong customer, or closed), and the route deliberately maps every one of those four distinct internal reasons to the exact same public response: a single 404 with a single message, "conversationId não encontrado para esta credencial." The route's own comment states the reasoning directly: distinguishing "this conversation exists but isn't yours" from "this conversation doesn't exist at all" would turn the endpoint into a tool an integrator (or anyone holding a valid API credential) could use to probe which conversation ids are real, one guess at a time. The specific reason is still recorded — but only in the internal log, never in the response a caller receives.

An integrator's own system stores a specific conversation id after a first exchange, and on a follow-up message deliberately sends that same id to keep the interaction continuous. Before the fix, the handler accepts the message, ignores the id entirely, and finds-or-creates a different conversation — the integrator's own system now believes it is continuing one thread while Synapse has silently attached the reply to another. After the fix, the same request either genuinely resumes that exact conversation, proven to belong to the caller, or receives an explicit, honest refusal — never a substitution the caller has no way to detect.

Centriu Synapse's messaging API now genuinely honors a request to resume a specific conversation, only after verifying it belongs to the calling credential, and refuses — rather than silently substitutes a different conversation — for every way that verification can fail.

This automation governs the public messaging API's own conversation-resolution logic — it does not change how conversations are found or created for integrators who never pass a conversationId, and it does not add a general cross-conversation search or listing capability; a caller can only resume a conversation whose exact id it already has.

The narrow fix — simply reading the value that was already being written and using it — would have solved the resume problem while opening a new one: without an ownership check, any caller could attempt to resume any conversation id and either succeed illegitimately or receive a response that reveals whether that id is real. Building the ownership check and the identical-refusal design in the SAME change, rather than as a follow-up, is what keeps "make the parameter work" from becoming its own, separate security defect.