This endpoint performs an upsert operation: it creates a new conversation segment or updates an existing one
based on the segment_id you provide.

If segment_id is provided: the segment with that ID is updated (you must be its creator or a master account),
otherwise a 404 (not found) or 403 (not allowed to manage) is returned.

If segment_id is not provided: a new segment is created. Only master accounts or accounts that can access all
conversations are allowed to create segments.

Private and shared segments

• is_private = false (default): the segment is public — visible to every account that can access all conversations.
• is_private = true: the segment is private — visible only to its creator, master accounts, and the accounts
  listed in shared_account_ids.
• shared_account_ids is only applied when is_private = true; it is ignored (and stored empty) for public segments.

The filters field — Predicate Structure

The filters field defines which conversations belong to this segment. It is a predicate tree:

Root object:

{ "operation": { ... } }

operation (optional) — either an operation node or a condition node.

Operation node (combines multiple predicates):

{ "type": "operation", "operator": "and", "predicates": [ ... ] }

• operator: "and" or "or" (lowercase)
• predicates: array of condition or operation nodes

Condition node (single rule):

{ "type": "condition", "target": "<target>", "operation": "<operation>", "value": "<value>" }

Conversation condition targets

Unless noted otherwise, the operation is is or is_not.

• conversation_status — conversation status. value: open, closed, snoozed.
• conversation_tag — priority tag. value: none, in_progress, waiting, priority.
• conversation_account — assigned teammate. value: account id (integer).
• conversation_team — assigned team. value: team id (integer).
• conversation_topic — conversation topic. value: topic id (integer).
• conversation_chatflow — originating chatflow. value: chatflow id (integer).
• conversation_origin_channel — channel the conversation started from. value: in_app, email, facebook, whatsapp.
• conversation_message_channel — channel of the conversation messages. value: in_app, email, facebook, whatsapp.
• conversation_csat — CSAT rating. value (integer): 1–5.
• conversation_ai_status — AI involvement. value: ai_involved, ai_not_involved, confirmed_resolved, assumed_resolved, escalated.
• conversation_escalation_type — AI escalation reason. value: one of low_confidence, missing_information, human_requested, exception, loop_detected, unknown, outside_mission, user_exited, node_deleted, interactions_depleted, content_security_policy, ai_disabled, ai_conversations_credit_exhausted, too_bothering, message_not_sent, conversation_frozen.
• conversation_opening_date / conversation_closing_date — date conditions. operation: on, before, after, exactly, more_than, less_than (days), more_than_hours, less_than_hours. value: number of days/hours, or a day reference depending on the operation.
• conversation_user — match on the conversation's contact. value is replaced by a nested predicate object using the contacts predicate schema (audience + operation).

Examples

Open conversations with the Priority tag:

{
  "operation": {
    "type": "operation",
    "operator": "and",
    "predicates": [
      { "type": "condition", "target": "conversation_status", "operation": "is", "value": "open" },
      { "type": "condition", "target": "conversation_tag", "operation": "is", "value": "priority" }
    ]
  }
}

Conversations assigned to team 7 that escalated from AI:

{
  "operation": {
    "type": "operation",
    "operator": "and",
    "predicates": [
      { "type": "condition", "target": "conversation_team", "operation": "is", "value": 7 },
      { "type": "condition", "target": "conversation_ai_status", "operation": "is", "value": "escalated" }
    ]
  }
}

Conversations whose contact has the vip tag:

{
  "operation": {
    "type": "condition",
    "target": "conversation_user",
    "operation": "is",
    "predicate": {
      "audience": "is_any_contact",
      "operation": { "type": "condition", "target": "tag", "operation": "is", "value": "vip" }
    }
  }
}

Errors

• 422 segment_invalid_filters — malformed predicate (unknown target, invalid operation, missing required fields)