Schemas

PHONE_NUMBER, WABA, BUSINESS, APP or MESSAGE_TEMPLATE.

This entity's own verdict.

Raw Meta tier code, read from the phone number's whatsapp_business_manager_messaging_limit field. Meta deprecated messaging_limit_tier on its side; this property keeps the name because it is this API's published contract.

The tier resolved to unique recipients reachable outside a customer service window per rolling 24 hours. Set per business portfolio and shared by every phone number in it. Null for TIER_UNLIMITED and for tiers Meta did not report - read it together with messaging_limit_tier to tell the two apart.

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.

Optional workspace hint: which organization to look the email up in first. Without it the server searches every tenant it has loaded and takes the first email match, which misses a workspace provisioned seconds ago on another replica and is ambiguous when the same email exists in several workspaces. Sent by the post-registration sign-in flow. Never bypasses the password or 2FA checks.

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. flow is an outbound WhatsApp Flow send (content follows FlowSendContent, requires wa_flows.send); flow_response is the matching inbound completion and is never sent by a caller — its content carries a masked summary only, never the customer's answers (see WhatsAppFlowCompletedEvent and GET /api/wa-flow-responses/{session_id} for the real values).

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).

The provider's own id for this message — a WhatsApp wamid.* from the Cloud API, a Meta message id for Instagram/Messenger, or the SMTP Message-ID for email. Distinct from _id, which is Omnistream's id and the one every REST endpoint takes and returns. Outbound messages are stored before the provider has assigned one, so this is null between the send call returning and the provider accepting the message (typically under a second). It is populated in place once message-sender gets the provider's response, and it is the key delivery receipts arrive under — see WebhookMessagePreview for how to correlate the two ids.

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. flow is an outbound WhatsApp Flow send (content follows FlowSendContent, requires wa_flows.send); flow_response is the matching inbound completion and is never sent by a caller — its content carries a masked summary only, never the customer's answers (see WhatsAppFlowCompletedEvent and GET /api/wa-flow-responses/{session_id} for the real values).

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. flow is an outbound WhatsApp Flow send (content follows FlowSendContent, requires wa_flows.send); flow_response is the matching inbound completion and is never sent by a caller — its content carries a masked summary only, never the customer's answers (see WhatsAppFlowCompletedEvent and GET /api/wa-flow-responses/{session_id} for the real values).

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). WhatsApp Business App coexistence accounts include initial_sync, which tracks the first contact/conversation/message sync after connection.

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.

wa_flows.id

Button label, no emoji

Entry screen id; defaults to the first screen

flow_action_payload.data (≤ 4 KB)

Set only when the pass was PARTIAL — nothing was demoted and no success was stamped

Per-Flow diagnostics from a pass that otherwise completed (for example a PUBLISHED Flow whose FLOW_JSON asset Meta does not expose). Distinct from error: the catalog was fully refreshed.

SHA-256 hex of the delivered answers — the completion object with flow_token removed, serialised with sorted keys and no whitespace

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, whatsapp.flow.completed, contact.created

Rule-scoped events carry rule_id / rule_name (plus snoozed_until on snooze); global events carry is_paused, pause_reason, paused_until and updated_by, and add auto: true when the resume was triggered by the schedule rather than by a person.

Matches one of the values from GET /api/outgoing-webhooks/events.

When the originating event was published, not when it was delivered.

Identifies the thread, NOT the message. A conversation is per contact, so an invoice and a later reminder to the same customer share it — never use it to attribute a delivery receipt to a message.

Nil UUID on message.status, which is not tied to a contact lookup.

Absent on conversation-level events that carry no message (conversation.resolved, conversation.assigned).

Omnistream's message id — a 24-character hex ObjectId, identical to the message_id returned by the send call and to Message._id.$oid.

Always outbound on message.status.

The message type (text, image, template, …), or the literal status_update on a message.status event.

Truncated body for message events; on message.status it is the fixed string Message <status> and carries no customer content.

The provider's id for the same message (e.g. wamid.HBgMNjI4MTcyMzQzMjEw...). Omitted from the JSON entirely — not sent as null — when unknown, which is the case for an outbound message whose provider response has not arrived yet, and for a failed status raised before the message ever reached the provider.

Present only on message.status; its presence is what makes the event a delivery receipt rather than a conversation transition.

Human-readable provider failure reason, on failed only.

Provider error code as a string, e.g. 131042.

Which layer reported the failure.

The body of one webhook delivery. Which variant arrives is determined by event_type: conversation and message events use WebhookEventPayload, automation events use WebhookAutomationPayload, and the "Send Test" button uses WebhookTestPayload. Note that data.message is an object on conversation events but a plain string on the test event — branch on event_type before reading it.

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