Sessions

Enriching with Metadata

Attach context about users, messages, and sessions for analytics and risk scoring

Metadata enriches your moderation requests with contextual information. This enables powerful features like Risk Scoring, detailed analytics, and better audit trails.

Metadata Levels

White Circle supports metadata at two levels:

LevelFieldPurpose
Sessionmetadata (top-level)Information about the overall session or environment
Messagemetadata (per message)Information about specific messages, users, or AI responses

Session-Level Metadata

Add context about the session or environment at the request level:

JSON

{
  "deployment_id": "your-deployment-id",
  "messages": [...],
  "metadata": {
    "session": {
      "timestamp": "2025-12-01T10:30:00Z"
    },
    "environment": {
      "app_version": "2.1.0",
      "platform": "ios",
      "feature": "customer-support-chat"
    }
  }
}

Session Fields

FieldTypeDescription
session.timestampstringISO 8601 timestamp when the session started

Environment Fields

The environment object accepts any key-value pairs for custom context:

JSON

{
  "environment": {
    "app_version": "2.1.0",
    "platform": "web",
    "feature": "ai-assistant",
    "region": "us-east-1",
    "ab_test": "new-moderation-v2"
  }
}

Values can be strings, numbers, or booleans.

Message-Level Metadata

Attach metadata to individual messages to provide context about who sent them and when:

JSON

{
  "deployment_id": "your-deployment-id",
  "messages": [
    {
      "role": "user",
      "content": "Hello, I need help",
      "metadata": {
        "user": {
          "id": "user-123",
          "email": "[email protected]",
          "name": "John Doe",
          "ip": "192.168.1.1"
        },
        "message": {
          "id": "msg-456",
          "timestamp": "2025-12-01T10:30:00Z"
        }
      }
    },
    {
      "role": "assistant",
      "content": "Hi! How can I help you today?",
      "metadata": {
        "assistant": {
          "model_name": "gpt-4o-mini",
          "latency": 1200
        },
        "message": {
          "id": "msg-457",
          "timestamp": "2025-12-01T10:30:01Z"
        }
      }
    }
  ]
}

User Metadata

Attach user information to messages with role: "user":

FieldTypeDescription
idstringYour internal user identifier
emailstringUser’s email or SHA-256 hash of email
namestringUser’s display name
ipstringUser’s IP address

Assistant Metadata

Attach AI response details to messages with role: "assistant":

FieldTypeDescription
model_namestringThe AI model used (e.g., “gpt-4o-mini”, “claude-3”)
provider_urlstringAPI endpoint URL
latencynumberResponse time in milliseconds

This data enables performance analytics in the White Circle dashboard.

Message Metadata

Attach identifiers and timestamps to any message:

FieldTypeDescription
idstringYour unique message identifier
timestampstringISO 8601 timestamp when the message was created

Full Example

curl -X POST https://eu.whitecircle.com/api/session/check \
  -H "Authorization: Bearer wc-your-api-key" \
  -H "Content-Type: application/json" \
  -H "whitecircle-version: 2025-12-01" \
  -d '{
    "deployment_id": "53e4567-e89b-12d3-a456-426614174000",
    "external_session_id": "support-chat-789",
    "metadata": {
      "session": {
        "timestamp": "2025-12-01T10:00:00Z"
      },
      "environment": {
        "app_version": "3.2.1",
        "platform": "web"
      }
    },
    "messages": [
      {
        "role": "user",
        "content": "I need to cancel my subscription",
        "metadata": {
          "user": {
            "id": "usr_abc123",
            "email": "[email protected]"
          },
          "message": {
            "id": "msg_001",
            "timestamp": "2025-12-01T10:00:05Z"
          }
        }
      },
      {
        "role": "assistant",
        "content": "I can help you cancel. Let me pull up your account.",
        "metadata": {
          "assistant": {
            "model_name": "gpt-4o-mini",
            "latency": 800
          },
          "message": {
            "id": "msg_002",
            "timestamp": "2025-12-01T10:00:06Z"
          }
        }
      }
    ]
  }'

Use Cases

Risk Scoring

Include user.id, user.email, or user.ip to enable risk scoring. White Circle aggregates violations per user to detect high-risk accounts.

Audit Trails

Include message.id and message.timestamp for detailed logging and compliance.

Analytics

Include environment data to segment moderation results by app version, platform, or feature.

Best Practices

Always include a user identifier for risk scoring

To use Risk Scoring, include at least one identifier in your message metadata (user.id, user.email, or user.ip):

JSON

{
  "metadata": {
    "user": {
      "id": "user-123",
      "email": "[email protected]",
      "ip": "203.0.113.10"
    }
  }
}
Use consistent identifiers

Always use the same user.id and normalized user.email for the same user across requests. Use user.ip as supplemental context, because IPs can change. Inconsistent identifiers create separate profiles and fragment risk scoring data.

Track AI model performance

If you use multiple AI models, track their performance:

JSON

{
  "metadata": {
    "assistant": {
      "model_name": "gpt-4o",
      "latency": 2500
    }
  }
}

This data appears in your White Circle dashboard for analysis.