Upsert Conversation

Upserting a conversation is a way to continuously send a transcript of an LLM interaction to, without needing to keep track of when the transcript ends. You can instead repeatedly send an updated conversation object as each new message arrives.

The semantics of upserting are this: If a conversation request is received that does not match a prior conversation, a new conversation is created. If the conversation request partially matches a prior conversation uploaded to, then the prior conversation is amended with the new messages.

To use upserting, you must:

  1. Always send conversation log requests with an increasing number of messages, always including the full conversation history in each request. Do not send log requests out of order.

  2. Always include the same metadata on each conversation log request.

  3. Always include at least 2 messages in the first upsert request. A conversation will only be considered a 'match' if new requests are prefixed with at least 2 messages from prior insertions/upsertions.

Upserting comes with caveats, since uses heuristics to perform the upsert. For example, if two sets of conversation requests contain the same set of messages, then these requests may be treated as the same conversation and be incorrectly deduplicated by Log events must happen within 6 hours of one another to be considered for matching. To prevent this from happening, consider attaching a unique identifier (such as a user ID) to the metadata object on each request. This will allow to correctly identify conversation uniqueness and prevent incorrect deduplication.

Upsert a Conversation


Records a conversation in Context.

Request Body




A Conversation object.

{ "status": "ok" }

Example Request

  "conversation": {
    "messages": [
        "role": "system",
        "message": "You are a LLM providing information about a local football club.",
        "event_timestamp": "2020-02-20T20:20:23Z"
        "role": "user",
        "message": "What time does the team arrive?",
        "event_timestamp": "2020-02-20T20:21:34Z"
        "role": "assistant",
        "message": "I'm not sure what time the team arrives.",
        "event_timestamp": "2020-02-20T23:20:40Z",
        "rating": -1
    "metadata": {
      "model": "gpt-3.5-turbo",
      "user_id": "2947451"

Example Response

{ "status": "ok" }

Last updated