Context Merging

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

First Request

Send the initial messages with an external_session_id:

{
  "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.

Subsequent Requests

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

{
  "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.

White Circle Sees the Full Context

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

[
  { "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?" }
]

Only the last message in the combined array is checked for policy violations and metrics. The previous messages provide context for the evaluation but are not themselves checked.

Requirements

Context merging requires an external_session_id. Without it, White Circle cannot identify which previous messages to merge.

Parameter	Required	Description
`external_session_id`	✓	Your tracking ID for the session
`include_context`		Set to `true` to enable merging. Defaults to `true` when `external_session_id` is provided

Default Behavior

Scenario	`include_context` default
`external_session_id` provided	`true` — context is merged automatically
No `external_session_id`	Not 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:

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

If you always want independent checks (no merging), explicitly set include_context: false.

Comparison: With and Without Context Merging

With Context Merging
Without Context Merging

Request 1:

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

Request 2:

{
  "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

Request 1:

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

Request 2:

{
  "deployment_id": "your-deployment-id",
  "messages": [
    { "role": "user", "content": "Hi there" },
    { "role": "assistant", "content": "Hello!" },
    { "role": "user", "content": "Tell me more" },
    { "role": "assistant", "content": "Sure, here's more info..." }
  ]
}

❌ You must send the full content every time

First Steps

Use Cases

Integrations

Sessions

Artifacts

Policy

Metric

User

How It Works

Requirements

Default Behavior

When to Use Context Merging

Disabling Context Merging

Comparison: With and Without Context Merging

​How It Works

​Requirements

​Default Behavior

​When to Use Context Merging

​Disabling Context Merging

​Comparison: With and Without Context Merging

How It Works

Requirements

Default Behavior

When to Use Context Merging

Disabling Context Merging

Comparison: With and Without Context Merging