Operator API Reference

Request Body

Response 201

{
  "success": true,
  "data": {
    "user": { "id": 12, "name": "Nino", "email": "nino@example.com", "...": "..." },
    "token": "1|abcdef123456..."
  },
  "message": "Registration successful."
}

Request Body

Response 200

{ "success": true, "data": { "user": {"...": "..."}, "token": "2|..." }, "message": "Login successful." }

Errors: 401 invalid credentials · 403 account suspended · 422 with data.requires_2fa: true when a TOTP/recovery code is missing or wrong.

Request Body (all fields optional)

Body: fcm_token (required string, max 500).

Body: is_online (required bool), away_message (optional string, max 500).

Body: name (required), domain (required), settings (optional object, merged into the default settings shown below).

Response 201

{
  "success": true,
  "data": {
    "id": 4,
    "name": "My Shop",
    "domain": "myshop.ge",
    "site_key": "b1e2c3d4-....-....-....-............",
    "settings": { "widget_color": "#2D3FE0", "widget_position": "bottom-right", "...": "..." },
    "unread_count": 0,
    "created_at": "2026-07-27T10:00:00.000000Z"
  },
  "message": "Site created."
}

Body (all optional): name, domain, and any settings.* key — e.g. settings.widget_color (hex), settings.widget_position (bottom-right/bottom-left), settings.pre_chat_form_enabled, settings.pre_chat_ask_name/_email/_phone (+ matching _required flags), settings.show_operator_status, settings.show_typing_indicator, settings.show_read_receipts, settings.offline_email_enabled, settings.offline_message, settings.welcome_message, settings.language.

Body: email (required, must belong to an existing Chattr account). Returns 422 if that user is already an operator on the site.

Returns 422 if {userId} is your own id — the owner can't remove themselves this way.

{
  "success": true,
  "data": {
    "site_id": 4,
    "total_conversations": 214,
    "open_conversations": 6,
    "resolved_today": 11,
    "avg_response_time_seconds": 87,
    "avg_rating": 4.6,
    "messages_count": 1830,
    "unassigned_rate_percent": 3.2,
    "department_volume": [ { "id": 1, "name": "Sales", "conversations": 90 } ],
    "tag_volume": [ { "id": 2, "name": "billing", "color": "#5e6c84", "conversations": 14 } ],
    "help_article_views": 58,
    "help_deflection_rate_percent": 21.3
  },
  "message": null
}

Query Parameters

Query: q (required, min 2 chars), site_id (optional). Internal notes are excluded from the message-body match. Capped at 50 results.

Body: status (required, open/pending/resolved). Setting resolved queues a conversation summarization job used for cross-session visitor memory.

Body: operator_id (nullable int — omit/null to unassign).

Body: department_id (nullable int, must belong to the conversation's site). Triggers the site's routing strategy (manual/round-robin/least-busy) for the new department.

Also flips ai_active to false — an operator joining always takes over from the AI.

Body: is_typing (required bool). Broadcasts OperatorTyping on conversation.{uuid}.

Query: per_page (max 100, default 50).

Request Body (multipart or JSON)

Body: body (required). Returns 403 if the message wasn't sent by you.

Body: emoji (required, max 10 chars). Calling it again with the same emoji from the same operator removes the reaction.

Body: feedback (required, good or bad). Returns 422 if the message wasn't AI-generated.

Body: body (required, max 10,000).

Pass site_id to include both that site's replies and your personal (site-less) ones. search matches shortcut, title, and body.

{
  "success": true,
  "data": [
    {
      "id": 9,
      "title": "Return Policy",
      "source_type": "url",
      "source_url": "https://myshop.ge/returns",
      "original_filename": null,
      "status": "ready",
      "chunk_count": 6,
      "error_message": null,
      "is_public": false,
      "slug": null,
      "category": null,
      "sort_order": 0,
      "views_count": 0,
      "created_at": "2026-07-01T09:00:00.000000Z"
    }
  ],
  "message": null
}

status transitions: pending → processing → ready (or failed, see error_message).

Multipart body: file (required, max 20MB, pdf,docx,txt,md,json). Returns the created document at status: "pending" and queues ingestion asynchronously (extraction → chunking → embedding).

Multipart body: file (required, max 50MB, .zip). Extracts up to 20 supported files (skips unsupported types, empty files, and anything over 20MB per entry — with a count of skipped files in the response message) and queues each as its own document.

Body: url (required, public http/https only), title (optional, defaults to the page's host+path).

Body (all optional): is_public (bool — exposes it in the widget's Help tab, auto-generates a slug the first time it's set), title, category, sort_order.

No body. Resets status to pending and re-dispatches ingestion — old chunks are deleted and replaced once the new ones finish embedding.