Introduction to contact segments

Read your contact segments and check whether a contact belongs to a given segment.

What is a contact segment?

A contact segment is a named group of contacts based on rules you define in the dashboard (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

Endpoints under /contacts/segments are read-only and require 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

Where do segments come from?

Segments are created and managed in the dashboard. The public API currently has no create/update/delete endpoints.

segments:write is reserved for future write endpoints and has no effect today.

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 contact sequence at exactly the contacts in a segment instead of hand-curating a list.
• Routing & SLAs — close VIP tickets 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).