Client Development & Integration

Last updated: 2026-02-18

Client Development Guide

This guide specifies the protocol for building client applications (Web, Mobile, Bots) that interact with the StopCyberViolences API. It covers session management, capability negotiation, and real-time communication.

1. Client Identification & Origin Tracking

All clients must identify themselves using an Origin Identifier. This field is mandatory for telemetry tracking (Langfuse) and capability profile resolution.

  • Field: origin (string) - Mandatory
  • Common Values: web_react, discord, dev_terminal.
  • Custom Clients: Use a unique slug (e.g., ios_app, android_app).

2. Capability Negotiation

The system uses a 3-tier negotiation system to adapt its behavior to the client’s features without requiring backend code changes for every new platform.

Priority Levels

  1. Explicit Declaration: Capabilities provided by the client in the init request (Highest priority).
  2. Registry Lookup: Backend looks up the origin in the client_registry (defined in api/config.py).
  3. Safe Defaults: System-wide safe defaults used if the origin is unknown and no explicit capabilities are provided.

Note: If the provided capabilities fail validation or are non-compliant, the system automatically falls back to the origin’s registry profile or safe system defaults.

Supported Capabilities

Flag Type Description
supports_sse Boolean If true, the backend enables streaming callbacks (Server-Sent Events) for this session.

3. Session Lifecycle

Initializing a Session

Endpoint: POST /api/v1/chat/init

Clients must initialize a session before sending messages. This establishes the user context, language, and negotiated capabilities.

Request Body:

{
  "user_id": "unique-persistent-user-id",
  "language": "fr",
  "monster": "betty",
  "origin": "web_react",
  "capabilities": {
    "supports_sse": true
  }
}

Response Metadata: The response contains a session_id which must be included in all subsequent requests. It also includes the initial monster state.

Sending Messages

Endpoint: POST /api/v1/chat

Request Body:

{
  "message": "Hello, I need help.",
  "user_id": "unique-persistent-user-id",
  "session_id": "uuid-from-init",
  "attachments": ["path/to/previously/uploaded/file.png"]
}

Handling Dynamic State

Clients must synchronize their UI based on the ChatResponse metadata returned in every turn:

  • Active Monster: The monster field indicates which character is speaking. The backend may change the monster mid-conversation (e.g., switching from a friendly guide to a specialized advisor).
  • Interactive Flags:
    • awaiting_emotion_selection: If true, the client should render an emotion picker using emotion_options.
    • awaiting_dropdown_selection: If true, the client should render a selection menu using dropdown_options.

4. Real-time Streaming (SSE)

If supports_sse is negotiated as true, clients should establish a persistent connection to receive tokens as they are generated.

Endpoint: GET /api/v1/chat/{session_id}/events/listen

Event Protocol

  1. handshake: Payload: {} (connection confirmation)
  2. settings: Payload: {"data": {"monster": "..."}} or {"data": {"language": "..."}} (state updates)
  3. terminate: Payload: {} (stream end signal)

5. Media & Accessibility

File Uploads

Upload media (screenshots, logs) to POST /api/v1/files/upload before sending the chat message. Use the returned file paths in the attachments array.

Voice Integration

For voice-first clients, use POST /api/v1/audio/transcribe to convert speech to text using the system’s transcription service.

6. General Implementation Checklist