> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whitecircle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="First Request">
    Send the initial messages with an `external_session_id`:

    ```json theme={null}
    {
      "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`.
  </Step>

  <Step title="Subsequent Requests">
    For new messages, send only the new content with `include_context: true`:

    ```json highlight={4} theme={null}
    {
      "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.
  </Step>

  <Step title="White Circle Sees the Full Context">
    When analyzing the second request, White Circle evaluates this combined content:

    ```json theme={null}
    [
      { "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?" }
    ]
    ```

    <Info>
      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.
    </Info>
  </Step>
</Steps>

## Requirements

<Warning>
  Context merging requires an <code>external\_session\_id</code>. Without it, White Circle cannot identify which previous messages to merge.
</Warning>

| 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

<AccordionGroup>
  <Accordion title="Real-time moderation" icon="comments">
    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
  </Accordion>

  <Accordion title="Reducing payload size" icon="minimize">
    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
  </Accordion>
</AccordionGroup>

## Disabling Context Merging

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

```json highlight={4} theme={null}
{
  "deployment_id": "your-deployment-id",
  "external_session_id": "conversation-123",
  "include_context": false,
  "messages": [
    { "role": "user", "content": "Check this message alone" }
  ]
}
```

<Tip>
  If you always want independent checks (no merging), explicitly set <code>include\_context: false</code>.
</Tip>

## Comparison: With and Without Context Merging

<Tabs>
  <Tab title="With Context Merging">
    **Request 1:**

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

    **Request 2:**

    ```json theme={null}
    {
      "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
  </Tab>

  <Tab title="Without Context Merging">
    **Request 1:**

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

    **Request 2:**

    ```json theme={null}
    {
      "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
  </Tab>
</Tabs>