Introduction to contact segments

What is a contact segment?

A contact segment is a named group of contacts based on rules you define in the dashboard or through the API (for example, “VIP customers” or “Trial users”). OpenCX evaluates those rules in the background and stores membership, so API reads are fast. A contact can belong to multiple segments at once.

Reading segments from the API

Reading endpoints under /contacts/segments requires segments:read. They answer four common questions:

What segments do I have? → List segments
What does this segment look like? → Get a segment
Which segments is this contact in? → List segments for a contact
Is this contact in this specific segment? → Check membership

Managing segments through the API

Writing requires segments:write, independently of segments:read:

Create a segment with a name and filter definition. Description is optional and defaults to null.
Update a segment by sending only changed fields. A supplied definition replaces the entire rule set; it is not merged. Send description: null to clear the description.
Delete a segment to remove its definition and stored memberships. Contacts are retained. Missing segment IDs return 404.

Filter definitions combine or groups containing and conditions. For example, match contacts whose email domain is example.com:

{
  "name": "Example customers",
  "definition": {
    "or": [{ "and": [{ "type": "contacts_email_domain_name_in", "domain_name_in": ["example.com"] }] }]
  }
}

A null definition matches all contacts. An empty or list is invalid; an empty and group matches all contacts. Creation and filter changes calculate membership in the background, so immediate membership reads may reflect the previous state. Renaming or changing a description does not trigger recalculation. Deleting a segment does not rewrite references in other segment definitions, actions, instructions, or workflows. Review those references before deletion. Companion supports creating, updating, and deleting segments for users with contact write permission. MCP clients expose the same operations as create_contact_segment, update_contact_segment, and delete_contact_segment.

Viewing and editing in the dashboard

Open Contacts → Segments to inspect saved segments, including those created through Companion, MCP, or the API. The list shows a condition summary; open it to see the complete definition with its groups. Name the segment, then choose Add first condition. Search for a contact detail, activity, or status. Add a description if useful. Select Include all contacts when everyone should belong. Use Add condition to narrow the audience: a contact must satisfy every condition in that section. Add an alternative creates another way to qualify, shown as Or include contacts who…. For example, one section can include Pro customers in France, and another can include VIP customers anywhere. A contact only needs to qualify for one section. For lists of names, email addresses, email domains, phone numbers, or contact IDs, use Add value for each additional entry. Each field is one value; line breaks inside a saved value stay part of that value. For new Contact attributes conditions, select an attribute name and an operator: equals, not equals, contains, exists, or not exists. Only comparison operators need a value. Use Add attribute to require another attribute to match. This is the single option for filtering saved contact fields, such as plan or country. Existing equality-only conditions remain editable with their saved grouping and matching behavior. Session attributes is separate: it matches attributes saved on a contact’s sessions, using exact key/value matches. Other condition types retain their own matching behavior; the five contact-attribute operators do not apply to every field. Existing contact and session attribute alternatives keep their original grouping, including untouched empty alternatives when you edit another alternative. Dates retain saved bounds and precision until edited; a missing lower or upper bound stays open-ended. References retain their saved IDs even if their display names cannot be loaded. Renaming a segment leaves its conditions unchanged. Empty groups and empty lists imported through the API are preserved and described in the editor; they are not silently removed. If a newer API introduces an unsupported condition, the editor preserves the complete definition and allows only name and description changes until the dashboard supports it. Contact read permission allows inspection; contact write permission is required to create, edit, or delete. Saving recalculates membership in the background when the definition changes.

Where segments are used

Segments are used to control AI behavior at runtime in two places:

Actions

Every action has a Restricted to segments list:

Empty list: action is available to all contacts (default).
Non-empty list: action is available only if the contact belongs to at least one listed segment.

A contact outside those segments cannot use or trigger that action. Anonymous contacts (no contactId yet) only get unrestricted actions.

AI knowledge / training instructions

Every AI instruction also has Restricted to segments, with the same behavior:

Empty list: instruction applies to everyone.
Non-empty list: instruction applies only to matching contacts.

How the restriction is enforced

When a message arrives, OpenCX checks the contact’s segment memberships and keeps only actions and instructions that apply to that contact. Membership is precomputed in the background, so runtime checks stay fast.

Use cases for segmentation

Beyond gating actions and instructions, segments are useful anywhere behavior should vary by cohort:

Workflow branching — use the Check Contact In Segment action to read isMember and route a workflow down a different branch (e.g. send a different email template to VIP vs Trial contacts).
Outbound sequencing — target a sequence at exactly the contacts in a segment instead of hand-curating a list.
Routing & SLAs — close VIP sessions faster by attaching a stricter SLA policy when the contact belongs to the segment.
Reporting & analytics — slice CSAT, handoff rate, or volume by segment to see how each cohort actually behaves.
Programmatic gating from your stack — use check_contact_in_segment from your backend or OpenCX MCP tools to gate features at the call site (for example, showing a different help-center widget per cohort).

​What is a contact segment?

​Reading segments from the API

​Managing segments through the API

​Viewing and editing in the dashboard

​Where segments are used

​Actions

​AI knowledge / training instructions

​How the restriction is enforced

​Use cases for segmentation