> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/api-reference/contacts/segments/list)
* **What does this segment look like?** → [Get a segment](/api-reference/contacts/segments/get)
* **Which segments is this contact in?** → [List segments for a contact](/api-reference/contacts/segments/list-for-contact)
* **Is this contact in this specific segment?** → [Check membership](/api-reference/contacts/segments/check)

## 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](/build-agents/actions) 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](/training/instructions) 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](/build-agents/workflows) 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](/api-reference/sequencing/create) 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](/api-reference/sla/policies) 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`](/api-reference/contacts/segments/check) from your backend or OpenCX MCP tools to gate features at the call site (for example, showing a different help-center widget per cohort).