Skip to main content

​
Overview

Some of the most useful things you can know about a call are not known when the call ends. A post-call classifier finishes a few minutes later. A quality workflow assigns a disposition. A downstream system records whether the customer called back. PATCH /v1/conversations/{conversation_id} lets you add those values to a conversation that already exists. Once a key is added, it is immediately available as a filter on the Conversations page and in the filter parameter of GET /v1/conversations, so you can compare metric results between segments — for example, how your agent scored on calls where called_back = 1 against calls where it is 0. This is the same endpoint used to attach audio after a call, and it follows the same shape: submit what you have at call end, add the rest when it arrives.

​
The two-call flow

1

Submit the conversation at call end

POST /v1/conversations:submit returns a conversation_id synchronously. Send whatever metadata you already have.
Store the returned conversation_id.
2

Add the new values when your analysis completes

PATCH /v1/conversations/{conversation_id} with a metadata object. The keys are merged into the metadata already on the conversation.
The conversation now carries channel, queue, called_back, csat_bucket and resolved_intent, and every one of them is filterable.

​
Filtering on what you added

Added keys behave exactly like metadata sent at submit time.
  • On the Conversations page, the key appears in the metadata filter and can be combined with metric, agent and date filters.
  • Through the API, filter with metadata.<key>:

​
Metrics are not re-run

Adding metadata does not run or re-run any metric. This is deliberate: the common case is enrichment for filtering, and re-running evaluation on every metadata write would be surprising and expensive. If you have a metric that depends on a key you added — for example, an LLM judge whose prompt references {{customer_metadata.resolved_intent}} — rerun it explicitly after the PATCH lands:
A metric whose prompt references a metadata key that is not present fails for that conversation. If a metric depends on a delayed value, expect it to fail on the first pass and succeed on the rerun after the metadata is added.

​
Additive only

Metadata is write-once per key. You can keep adding new keys to a conversation, but you cannot change a key that already has a value.
  • Adding a key that is not yet present succeeds.
  • Patching a key that already holds a value returns 409 ALREADY_EXISTS, and nothing is written.
  • A stored 0, "" or null counts as a value. It is a set key, not an empty slot.
This keeps a metric score reproducibly tied to the inputs it was scored against. If you need to correct a value, submit a new conversation with a new external_conversation_id.

​
Keys you cannot set

Some metadata keys identify the conversation rather than describe it, and are rejected with 400 INVALID_ARGUMENT: conversation_id, external_conversation_id, call_id, trace_id, langfuse_trace_id, observation_id, langfuse_observation_id, project_id, environment, occurred_at Set these when you submit the conversation.

​
Limits

  • One patch target per request. Send metadata or an audio field, not both. Use two calls if you need to do both.
  • At most 100 keys per request; key names are limited to 200 characters.
  • Values may be strings, numbers, booleans, arrays or objects.