Schemas

TOTP authenticator code, when completing a TOTP-2FA login.

The emailed OTP, when completing an email-2FA login.

When true, ask the server to email an OTP instead of verifying a code on this request.

Cloudflare Turnstile token, when the CAPTCHA widget is enabled.

When true, issue a longer-lived "remember me" session (7 days, cookie Max-Age and JWT exp) instead of the default TTL. Only takes effect after 2FA succeeds; ignored on 2FA-challenge responses.

JWT token

True when platform-level Google SSO login is configured.

Cloudflare Turnstile token, when the CAPTCHA widget is enabled.

True when an enabled company SSO provider accepts the email's domain.

Relative URL that begins the company SSO flow (carries a single-use ticket). Null when no provider matches.

Server-side ceremony id; echo it back on the matching verify call.

WebAuthn options to pass to the browser (navigator.credentials.create for registration, navigator.credentials.get for login).

Friendly device name shown in the passkey list.

True when a client secret is stored. The secret itself is never returned.

OIDC issuer base URL (must serve an OIDC discovery document).

Stored encrypted at rest; never returned by the API.

The complete set of conversation states. Mirrors ConversationStatus in crates/omni-common/src/models/conversation.rs. pending and expired were removed by migrations/20260326000039_simplify_conversation_statuses.sql (pending → open, expired → resolved) and snoozed was added by migrations/20260519000012_conversation_snooze.sql. Passing a removed value as a status filter is rejected with 400 before the handler runs, because the query struct deserializes straight into this enum. A snoozed conversation is hidden from the inbox until snoozed_until passes, at which point it reopens automatically.

whatsapp, instagram, or email

Full name of the assigned agent (null when unassigned)

All co-assignees (human agents and/or AI agent) attached to this conversation via the conversation_assignees junction, ordered by assignment time. assigned_agent_id remains the denormalized primary.

Discriminates human vs AI assignee

Set when this assignee is a human agent

Set when this assignee is an AI agent

Display name of the human or AI agent

Set to null to unassign

Human agent to add as co-assignee

AI agent to hand the conversation off to

The complete set of conversation states. Mirrors ConversationStatus in crates/omni-common/src/models/conversation.rs. pending and expired were removed by migrations/20260326000039_simplify_conversation_statuses.sql (pending → open, expired → resolved) and snoozed was added by migrations/20260519000012_conversation_snooze.sql. Passing a removed value as a status filter is rejected with 400 before the handler runs, because the query struct deserializes straight into this enum. A snoozed conversation is hidden from the inbox until snoozed_until passes, at which point it reopens automatically.

Denormalized display name, for tooltip rendering

Mirrors MessageType in crates/omni-common/src/models/message.rs. contacts (a shared contact card) and postback (a tapped button) are emitted by the channel engines; unknown covers anything the parsers did not recognise.

Free-form JSON whose shape depends on type. READING a stored message: text lives under body. Every channel engine normalises inbound content to {"body": "..."} before storing it (see the parser modules in crates/chat-engine), and outbound text stored through this API arrives the same way from the first-party clients. The server's own reader, extract_content_text in crates/api-gateway/src/routes/messages/handlers.rs, tries body, then text, then caption, then subject — a consumer should do the same rather than reading one key. Email messages carry body, subject, html and text together. WRITING via SendMessageRequest: either key works. The WhatsApp sender reads text first and falls back to body (crates/message-sender/src/whatsapp.rs), and whichever you send is stored verbatim — so send body if you want reads and writes to agree.

MongoDB ObjectId in extended JSON — {"$oid": "<24-hex>"}, NOT a bare string. The server field is a bson::oid::ObjectId, which serializes to this wrapper object under serde_json. Note the asymmetry with MessageSearchResult._id, which IS a plain hex string: the search handler flattens it with oid.to_hex() while building the result. The same logical value therefore arrives in two different shapes depending on the endpoint. MessageListResponse.next_cursor and the cursor query parameter both use the plain hex form, so the value read from here must be unwrapped before it can be used as a cursor. Absent on a message whose id was never assigned (the field is skipped when null).

Agent who sent this outbound message. Absent on inbound and system-generated messages.

Denormalized display name of the sending agent

CRM-internal agent reactions. Never forwarded to the external channel. Absent when nobody has reacted.

Why delivery failed — human-readable, only set when status is failed

Provider error code for the failure (e.g. "132001" from Meta)

Origin of the failure ("meta", "smtp", or "system")

Raw provider error object (sanitized), for support/debugging

MongoDB ObjectId hex for next page

MongoDB ObjectId as a plain 24-character hex string — the search handler flattens it with oid.to_hex(). This differs from Message._id, which is the extended-JSON object {"$oid": ...}.

Mirrors MessageType in crates/omni-common/src/models/message.rs. contacts (a shared contact card) and postback (a tapped button) are emitted by the channel engines; unknown covers anything the parsers did not recognise.

Free-form JSON whose shape depends on type, copied verbatim from the stored message. Text lives under body; read body, text, caption, subject in that order. See Message.content.

Matched text with <mark> tags around the search terms. Built from customer-supplied content — escape everything outside the marks before rendering.

whatsapp, instagram, email, or messenger

Page size actually applied, clamped to 50

Mirrors MessageType in crates/omni-common/src/models/message.rs. contacts (a shared contact card) and postback (a tapped button) are emitted by the channel engines; unknown covers anything the parsers did not recognise.

Free-form JSON. For text: {"text": "Hello"} or {"body": "Hello"} — the WhatsApp sender reads text first and falls back to body. For image: {"url": "...", "caption": "..."}. Whichever key you send is stored verbatim and read back on Message.content, so sending body keeps writes and reads on the same key that every inbound message already uses.

whatsapp, instagram, or email

JSON array of tag strings

Matching contacts across all pages

1-based page number

Page size actually applied, clamped to 100

Must contain @

Defaults to "agent" if omitted

Admin only

Admin only

FK to quick_reply_categories

Percentage (0.0 - 100.0)

YYYY-MM-DD

7d, 30d, or 90d

Free-form JSON message content

Must be in the future (UTC)

not_started means the conversation was business-initiated (outbound template/campaign) and the customer has not replied yet: the SLA clock is idle and elapsed fields are null.

whatsapp, instagram, email, or messenger

Channel configuration (sensitive fields masked)

whatsapp, instagram, email, or messenger

Unique key within a channel (e.g. wa-123456789)

Account configuration (sensitive fields masked)

Computed webhook URL for this account

whatsapp, instagram, email, or messenger

Required for non-WhatsApp channels. Auto-derived from phone_number_id for WhatsApp.

WhatsApp Business Account ID

BCP-47 language code (e.g. id, en_US)

Meta template components array (HEADER, BODY, FOOTER, BUTTONS)

Template ID assigned by Meta

Public MinIO URL for the header media (IMAGE/VIDEO/DOCUMENT)

Lowercase letters, numbers, and underscores only. Max 512 chars.

Meta template components array

Use specific WABA account. Falls back to META_WABA_ID env var.

JSON array of subscribed event type strings

HMAC signing secret. Write-only — never returned in responses. The staged rotation secret (secret_next) is likewise never returned; a pending rotation is only visible via secret_rotated_at.

When the current secret-rotation overlap window started. Null when no rotation is in progress (cleared on complete, cancel, or the 24-hour auto-promote).

Must start with http:// or https://

Valid types: message.received, message.sent, message.status, conversation.created, conversation.resolved, conversation.assigned, contact.created

pending = queued, awaiting the next scheduler tick; sending = claimed by a dispatcher worker (15-minute lease, reclaimed if the lease expires); success = delivered (HTTP 2xx); failed = last attempt failed but retries remain; dead_letter = terminal (attempts exhausted, webhook missing/inactive, or URL blocked) — never retried automatically, only a replay re-queues it.

Delivery attempts before dead-lettering (default 8)

Failed but still retryable (attempt < max_attempts)

Terminally failed deliveries awaiting replay or 30-day cleanup

Average milliseconds between created_at and completed_at

Optional custom secret (16–255 chars after trimming). Omit to have the server generate a 64-character lowercase-hex secret.

The new signing secret — shown once, never returned again

Start of the dual-signature overlap window

Human-readable note that the previous secret keeps working for up to 24 hours or until the rotation is completed

Deliveries to replay; only failed/dead_letter rows are reset

Always "queued" on success

Role bawaan sistem tidak dapat dihapus atau diubah namanya

Role bawaan sistem tidak dapat dihapus atau diubah namanya

Daftar kode izin yang dimiliki role ini

Kode izin dalam format category.action, misal: campaigns.manage

Nama role (akan dinormalisasi ke huruf kecil). Tidak boleh sama dengan nama role sistem.

Daftar kode izin yang akan diberikan ke role ini

Tidak dapat diubah untuk role sistem

Menggantikan seluruh daftar izin role (replace, bukan merge)

20 karakter pertama dari plaintext key (bukan rahasia); key lama tetap 12 karakter

JSON array of scope strings

Source-IP allow list untuk key rest. Setiap entri berupa satu alamat IP (IPv4/IPv6) atau blok CIDR, mis. 203.0.113.10, 203.0.113.0/24, 2001:db8::/32. Array KOSONG (default) berarti key diterima dari IP mana pun. Bila tidak kosong, request dari IP di luar daftar ditolak dengan 401 generik sebelum handler dieksekusi.

Plaintext API key — hanya ditampilkan sekali saat pembuatan. Simpan dengan aman.

Tanggal kedaluwarsa opsional (UTC)

Opsional. Source-IP allow list (single IP dan/atau CIDR, IPv4/IPv6) untuk key rest. Kosong/diabaikan berarti key diterima dari IP mana pun. Entri invalid, string kosong, atau daftar melebihi 50 entri ditolak dengan 422.

Pengganti source-IP allow list. Array kosong menghapus pembatasan (key kembali diterima dari IP mana pun). Validasi sama dengan saat create. Update tidak me-rotate key.

How the campaign was created: manual (broadcast UI) or api (POST /api/messages/template).

Meta template category, re-synced from Meta on every POST /api/wa-templates/sync.

How the campaign was created: manual (broadcast UI) or api (POST /api/messages/template).

Meta template category, re-synced from Meta on every POST /api/wa-templates/sync.

How the campaign was created: manual (broadcast UI) or api (POST /api/messages/template).

First page of recipients, ordered by created_at ascending — identical to GET /api/campaigns/{id}/recipients?page=1. The key is ABSENT unless include=recipients was passed; an empty array means the campaign genuinely has no recipients. To detect further pages, compare total_recipients with this array's length and page through the recipients endpoint.

Template harus berstatus APPROVED