Meeting Liveness Bot — Integration Guide¶

This guide walks through a production backend integration: credentials, session management, webhook handling, and the optional interviewer view.

Before You Start¶

What You Need From Moveris¶

Contact the Moveris team for key provisioning, bot URL, org branding, and webhook setup.

What You Build¶

Authentication¶

All backend requests to the bot use:

Authorization: Bearer sk-bot-<your-bot-key>
Content-Type: application/json

No browser login or session cookie is required for M2M integration.

The bot validates your key against the Moveris Developer Portal API and loads organization branding for the meeting.

sequenceDiagram
    participant BE as Your backend
    participant Bot as Meeting Liveness Bot
    participant API as Moveris API

    BE->>Bot: Authorization: Bearer sk-bot-*
    Bot->>API: POST /api/auth/v1/org-bot-keys/validate/ body key
    API-->>Bot: success envelope + org branding
    Bot-->>BE: 200 session created or 401

Validate request (called by the bot, not your backend):

POST https://<moveris-api-url>/api/auth/v1/org-bot-keys/validate/
Content-Type: application/json

{ "key": "sk-bot-<your-bot-key>" }

Success (standard Moveris API envelope):

{
  "data": {
    "organization_id": 42,
    "organization_name": "Your Organization",
    "organization_slug": "your-org",
    "bot_display_name": "Liveness Verifier",
    "logo_url": "https://example.com/logo.png",
    "primary_color": "#0066ff"
  },
  "success": true,
  "message": "OK"
}

End-to-End Flow¶

sequenceDiagram
    participant Backend as Your backend
    participant Bot as Meeting Liveness Bot
    participant Provider as Meeting provider
    participant Moveris as Moveris API
    participant Webhook as Your webhook endpoint
    participant Observer as Interviewer (optional)

    Backend->>Bot: POST /api/sessions + Bearer sk-bot-*
    Bot->>Provider: Create bot for meeting URL
    Bot-->>Backend: sessionId, interviewToken
    Backend->>Observer: Share /interview/token (optional)
    Provider->>Bot: WebSocket video frames
    Bot->>Moveris: POST /api/v1/fast-check per participant
    Moveris->>Webhook: verification.completed
    Backend->>Backend: Correlate session_id to participant

Integration timeline¶

flowchart TB
    S1[1. Schedule / start meeting] --> S2[2. POST /api/sessions]
    S2 --> S3[3. Store sessionId + interviewToken]
    S3 --> S4[4. Share /interview/token optional]
    S4 --> S5[5. Bot joins call]
    S5 --> S6[6. Webhook verification.completed per participant]
    S6 --> S7[7. Interviewer sees SSE updates optional]
    S7 --> S8[8. Meeting ends or DELETE session]

See How It Works for the difference between bot status (SSE) and verdict webhooks.

Creating a Session¶

Request¶

POST https://<bot-url>/api/sessions
Authorization: Bearer sk-bot-<your-bot-key>
Content-Type: application/json

{
  "meetingUrl": "https://meet.google.com/abc-defg-hij",
  "model": "mixed-10-v3_1"
}

Response¶

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "botId": "bot_abc123",
  "status": "bot_created",
  "interviewToken": "eyJzZXNzaW9uSWQiOiI1NTBlODQwMC4uLiJ9.abc123sig",
  "message": "Bot is being created and will join the meeting shortly"
}

Model selection¶

The bot passes your model to POST /api/v1/fast-check with source: "live". Frame count follows the model alias (for example 10 frames for mixed-10-v3_1_1).

Full comparison: Overview — Models · Model Versioning & Frames

Targeted Participant Scanning¶

By default the bot scans every participant it sees on camera. Pass targetParticipantNames to scan only specific people, and excludeParticipantNames to skip others.

How matching works¶

The bot matches a participant's display name against your list in two tiers:

1. Fuzzy match — handles typos, reordered names, and partial names. A close match resolves immediately with no extra calls.
2. LLM confirmation (optional) — for borderline cases, a fast LLM yes/no check decides. Moveris enables this step on the bot deployment; you don't configure it.

excludeParticipantNames uses the same matching but rejects matches — put interviewer or host names there so they are never scanned.

Request example¶

Scan only the candidate, skip the interviewer:

{
  "meetingUrl": "https://meet.google.com/abc-defg-hij",
  "model": "mixed-10-v3_1",
  "targetParticipantNames": ["John Smith"],
  "excludeParticipantNames": ["Jane Doe"]
}

When a participant is matched, the bot pins their video feed and waits for them to speak before collecting frames. This ensures frames capture the person's live face rather than an idle thumbnail.

Participant stages¶

In targeted mode each matched participant moves through these stages, surfaced on the session SSE stream:

Verdicts are still delivered through your verification.completed webhook with the same correlation rules.

Frame Quality Gating¶

Before a frame enters the accumulator, the bot evaluates it for capture quality. A rejected frame resets that participant's buffer so the liveness model still receives consecutive frames.

What is checked¶

Face checks load after a short model warmup. Until then, only blur and brightness run.

SSE event¶

Rejected frames emit frame-quality-rejected on the session events stream (throttled to about once per second per participant):

{
  "participantId": "p1",
  "participantName": "John Smith",
  "reason": "too-blurry",
  "framesCollected": 0,
  "framesRequired": 10
}

Use reason to show interviewer guidance. Configure face checks with Moveris or pass faceGate on session create when your deployment allows it.

Background Segmentation¶

Optional background segmentation replaces each participant's background with neutral grey before frames go to POST /api/v1/fast-check.

Pass bgSegmentation: true (or false) on POST /api/sessions. If omitted, the bot uses the deployment default from Moveris. When enabled, the analysis request includes bg_segmentation: true (same field documented on Fast Check Crops).

Receiving Results via Webhook¶

Configure your webhook in the Developer Portal on the same Moveris API key the bot uses. Subscribe to verification.completed (and optionally verification.failed).

After each participant analysis, Moveris sends an HTTP POST to your registered URL. This uses the same delivery format as the REST API—not a separate bot-specific event name.

Headers¶

Payload (verification.completed)¶

{
  "event": "verification.completed",
  "session_id": "a3f7c291-8b2e-5c1d-9f0a-1b2c3d4e5f6a",
  "timestamp": "2026-06-01T15:26:42.123456Z",
  "data": {
    "verdict": "live",
    "real_score": 0.88,
    "score": 88.0,
    "confidence": 0.93,
    "type": "VERY HIGH",
    "session_id": "a3f7c291-8b2e-5c1d-9f0a-1b2c3d4e5f6a",
    "model": "mixed-10-v3_1",
    "input_source": "live",
    "processing_ms": 1240,
    "frames_processed": 10,
    "tenant_metadata": {
      "participant_id": "p1",
      "participant_name": "John Doe",
      "bot_session_id": "<parent_session_id>"
    },
    "warning": null,
    "created_at": "2026-06-01T15:26:42.123456Z",
    "frames": [
      "https://storage.example.com/frames/.../frame-0.png?token=..."
    ]
  }
}

Correlating Webhooks to Participants¶

The bot assigns each participant a deterministic Moveris session ID before calling fast-check:

namespace  = "5e8cf7e0-e4c4-4b3a-8d3a-2f1c3b4a5e6f"
moveris_session_id = uuid_v5(namespace, "<botSessionId>-<participantId>")

flowchart LR
    A["POST /api/sessions → sessionId"] --> C["uuid_v5(namespace, sessionId + '-' + participantId)"]
    B["participantId from meeting"] --> C
    C --> D["Webhook session_id"]

The webhook payload does not include participant_id or participant_name. Use one of these patterns:

Example (Python)¶

import uuid

NAMESPACE = uuid.UUID("5e8cf7e0-e4c4-4b3a-8d3a-2f1c3b4a5e6f")

def moveris_session_id(bot_session_id: str, participant_id: str) -> str:
    return str(uuid.uuid5(NAMESPACE, f"{bot_session_id}-{participant_id}"))

def find_participant_for_webhook(bot_session_id: str, webhook_session_id: str, participant_ids: list[str]) -> str | None:
    for pid in participant_ids:
        if moveris_session_id(bot_session_id, pid) == webhook_session_id:
            return pid
    return None

Webhook Security¶

Verify X-Webhook-Signature with your webhook secret. See Webhook Setup Guide — Verifying the Signature.

Optional: Poll Session Results¶

If you need participant names or IDs alongside webhooks, poll while the meeting is active:

GET https://<bot-url>/api/sessions/<sessionId>
Authorization: Bearer sk-bot-<your-bot-key>

The response includes results keyed by participantId, each with verdict, score, moverisSessionId, and related fields. Use this to build your correlation table or to backfill if a webhook was missed.

Optional: Manual Re-scan¶

Trigger a new analysis for one or all participants (same session, bot still in call):

POST https://<bot-url>/api/sessions/<sessionId>/retry/<participantId>
POST https://<bot-url>/api/sessions/<sessionId>/retry-all
Authorization: Bearer sk-bot-<your-bot-key>

Each successful re-scan can produce another verification.completed webhook with the same correlation rules.

Interviewer View¶

The interviewToken enables a read-only live dashboard—no bot API key or Google login.

URL Format¶

https://<bot-url>/interview/<interviewToken>

What the Page Does¶

1. Validates the token via GET /api/interview/<token>
2. Opens SSE at GET /api/interview/<token>/events
3. Shows participants and verdicts as analysis completes

The token expires 24 hours after creation.

Typical Usage¶

1. Your backend creates a session before the interview.
2. Extract interviewToken from the response.
3. Send the interview URL to the observer.
4. They open it during the call and monitor results in real time.

Stopping a Session¶

DELETE https://<bot-url>/api/sessions/<sessionId>
Authorization: Bearer sk-bot-<your-bot-key>

Response

{
  "status": "stopped"
}

Error Handling¶

Bot API errors¶

{
  "error": "Human-readable error message"
}

Analysis failures¶

If fast-check fails after validation, you may receive verification.failed instead of verification.completed. The payload includes data.error and no verdict. Subscribe to both events in the Developer Portal if you need operational alerts.

Slack Notifications¶

When enabled on your bot deployment, Moveris can post formatted liveness verdicts to a Slack channel after each participant check.

Each message includes:

• Environment label (for example Development, Staging, Production)
• Participant name and verdict (Live, Fake, Inconclusive, or Error)
• Score, model, processing time, and Moveris session_id
• Meeting URL when available

Your backend integration should still rely on verification.completed webhooks for pass/fail decisions. See How It Works — Two Ways You Receive Updates. Contact the Moveris team to enable Slack alerts on your deployment.

Production Checklist¶

• [ ] Bot API key stored in server-side secrets
• [ ] Moveris API key and webhook registered on the same Developer Portal key (configured by Moveris on the bot)
• [ ] Webhook URL is HTTPS and publicly reachable
• [ ] Signature verification implemented (X-Webhook-Signature)
• [ ] Subscribed to verification.completed (and verification.failed if needed)
• [ ] Correlation tested: sessionId + participantId → webhook session_id
• [ ] Model chosen (V3.1 recommended for new integrations)
• [ ] Interviewer link flow tested (if used)
• [ ] DELETE /api/sessions/:id tested for early termination
• [ ] Re-scan behavior understood if participants toggle cameras

Contact¶

For bot API key provisioning, webhook configuration, bot URL, or integration support, contact the Moveris team.

Related¶

• How It Works — Pipeline, auth, and notification channels
• Overview — Capabilities and models
• Quick Start — Minimal first session
• Session Lifecycle — Bot states and camera re-scan
• API Reference — Complete endpoint reference
• Webhook Setup Guide — Portal configuration with screenshots