Sessions

Context Merging

Send only new messages and let White Circle handle the history

Context merging allows you to send only the new messages rather than the entire history every time. White Circle automatically combines your new messages with previously submitted content.

This reduces payload size, simplifies your code, and ensures consistent moderation across the full context.

How It Works

  1. First Request

    Send the initial messages with an external_session_id:

    JSON

    {
      "deployment_id": "your-deployment-id",
      "external_session_id": "conversation-123",
      "messages": [
        { "role": "user", "content": "Hello, I need help with my account" },
        { "role": "assistant", "content": "Hi! I'd be happy to help. What's the issue?" }
      ]
    }

    White Circle stores these messages associated with conversation-123.

  2. Subsequent Requests

    For new messages, send only the new content with include_context: true:

    JSON

    {
      "deployment_id": "your-deployment-id",
      "external_session_id": "conversation-123",
      "include_context": true,
      "messages": [
        { "role": "user", "content": "I forgot my password" },
        { "role": "assistant", "content": "I can help you reset it. What's your email?" }
      ]
    }

    White Circle automatically prepends the previous messages before analyzing.

  3. White Circle Sees the Full Context

    When analyzing the second request, White Circle evaluates this combined content:

    JSON

    [
      { "role": "user", "content": "Hello, I need help with my account" },
      { "role": "assistant", "content": "Hi! I'd be happy to help. What's the issue?" },
      { "role": "user", "content": "I forgot my password" },
      { "role": "assistant", "content": "I can help you reset it. What's your email?" }
    ]

Requirements

ParameterRequiredDescription
external_session_id✓Your tracking ID for the session
include_contextSet to true to enable merging. Defaults to true when external_session_id is provided

Default Behavior

Scenarioinclude_context default
external_session_id providedtrue — context is merged automatically
No external_session_idNot applicable — each request is independent

When to Use Context Merging

Real-time moderation

As new content is generated, send each new exchange with include_context: true. White Circle maintains the full context for accurate policy evaluation.

This is especially important for detecting:

  • Multi-turn jailbreak attempts where users gradually push boundaries
  • Context-dependent violations that only make sense with history
  • Patterns of behavior across the session
Reducing payload size

For long sessions, sending the full history every time can be expensive and slow. With context merging:

  • You send only new messages
  • Requests are smaller and faster
  • White Circle handles the history

Disabling Context Merging

If you want to check messages in isolation (without previous context), explicitly set include_context: false:

JSON

{
  "deployment_id": "your-deployment-id",
  "external_session_id": "conversation-123",
  "include_context": false,
  "messages": [
    { "role": "user", "content": "Check this message alone" }
  ]
}

Comparison: With and Without Context Merging

Request 1:

JSON

{
  "deployment_id": "your-deployment-id",
  "external_session_id": "session-123",
  "messages": [
    { "role": "user", "content": "Hi there" },
    { "role": "assistant", "content": "Hello!" }
  ]
}

Request 2:

JSON

{
  "deployment_id": "your-deployment-id",
  "external_session_id": "session-123",
  "include_context": true,
  "messages": [
    { "role": "user", "content": "Tell me more" },
    { "role": "assistant", "content": "Sure, here's more info..." }
  ]
}

✅ White Circle analyzes all 4 messages together