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

# Managing Contacts, Tags, and Custom Fields in Fliqr AI

> Every person who messages you becomes a Contact. Learn how tags, custom fields, and segments let you store, find, and act on contact data.

Every time someone sends you a message — on WhatsApp, Instagram, Messenger, Telegram, SMS, Email, or your website chat — Fliqr AI creates or updates a Contact record. That record holds the identifiers for each channel the person has used, along with any data you have collected about them during conversations. This page explains the Contact data model, how to organize contacts with tags and custom fields, and how to filter them into segments for targeting and automation.

## Overview

Contacts are the central data object in Fliqr AI. Flows capture data into contact fields, AI Agents read and write those fields, Automation Rules fire based on field values and tags, and broadcasts reach filtered subsets of your contact list. Getting your contact data model right early saves significant rework later.

## System Fields

Fliqr AI populates the following fields automatically for every Contact:

| Field                   | Description                                                                  |
| ----------------------- | ---------------------------------------------------------------------------- |
| `first_name`            | Pulled from the channel profile at opt-in                                    |
| `last_name`             | Pulled from the channel profile at opt-in                                    |
| `phone`                 | Set when the contact messages via WhatsApp, SMS, or Voice                    |
| `email`                 | Set when the contact messages via Email or provides it during a conversation |
| `locale`                | Detected from the channel (e.g., `en_US`, `pt_BR`)                           |
| `channel`               | The channel through which the contact first subscribed                       |
| `last_interaction_date` | Updated automatically on every inbound message                               |

System fields are read-only — they are maintained by the platform and cannot be deleted, though you can overwrite `email` and `phone` programmatically when a contact provides updated details.

## Tags

Tags are plain-text labels you attach to contact records. They serve two purposes:

1. **Filtering** — build audience segments and broadcast lists by combining tag conditions.
2. **Triggering** — fire Automation Rules when a specific tag is applied or removed.

Common tag patterns:

* Lifecycle stage: `lead`, `qualified`, `customer`, `churned`
* Engagement level: `hot-lead`, `cold-lead`, `vip`
* Support context: `open-ticket`, `escalated`
* Content preference: `interested-in-plan-pro`, `attended-webinar-2025`

Tags have no inherent hierarchy or data — they are boolean (present or absent). If you need to store a value, use a Custom User Field instead.

## Custom User Fields (CUFs)

Custom User Fields let you store per-contact data beyond the system fields. You define the field name, type, and default value. Available types:

| Type        | Example use                            |
| ----------- | -------------------------------------- |
| **Text**    | `company_name`, `preferred_language`   |
| **Number**  | `order_count`, `lifetime_value`        |
| **Date**    | `appointment_date`, `trial_expiry`     |
| **Boolean** | `opted_in_to_sms`, `has_made_purchase` |

### Using CUFs in conversations

Reference a CUF in any message block using double curly braces: `{{appointment_date}}`. AI Agents also have direct access to CUF values — you can instruct the Agent to read or update them mid-conversation without a separate Flow step.

Flows capture CUF values through the **User Input** block (free-text entry) or the **Set Custom Field** block (static or computed value). The **External Request** block can parse an API response and write the result directly into a CUF.

<Tip>
  Use `snake_case` for all CUF names — for example, `appointment_date` rather than `Appointment Date` or `appointmentDate`. Template variables are case-sensitive, and consistent naming avoids broken references across Flows.
</Tip>

## Segments

Segments are saved filters over your contact list. You combine conditions using AND/OR logic:

* Tag is / is not present
* CUF value equals / contains / is greater than / is empty
* Channel is (WhatsApp, Instagram, etc.)
* Last interaction date is before / after a given date

\[SCREENSHOT: Contacts list with tag filters and custom field columns visible]

Segments update in real time — a contact enters or exits a segment as their data changes. Use segments to:

* Build broadcast audiences (send a message to everyone tagged `hot-lead` who last interacted within 7 days).
* Trigger re-engagement campaigns based on `last_interaction_date`.
* Monitor the size of each lifecycle stage over time.

## Steps: Manage Contacts Day-to-Day

<Steps>
  <Step title="Open your Contacts list">
    In the left sidebar, click **Contacts**. The list shows all contacts across every channel by default, sorted by most recent interaction.
  </Step>

  <Step title="Filter by tag or field">
    Click **Add Filter** and choose a condition — for example, **Tag is** `hot-lead`. Stack additional conditions to narrow the list. Click **Save as Segment** to preserve this filter for reuse.
  </Step>

  <Step title="Add a tag manually">
    Open a contact record by clicking their name. In the **Tags** panel, type a tag name and press Enter. You can also remove tags from this panel. Bulk-tag contacts by selecting multiple rows in the list view and choosing **Apply Tag** from the action bar.
  </Step>

  <Step title="Edit a Custom User Field">
    Inside the contact record, find the **Custom Fields** panel. Click any field value to edit it inline. Changes take effect immediately and are reflected in any active conversation with that contact.
  </Step>

  <Step title="Export contacts as CSV">
    Apply any filter or segment, then click **Export** in the top right of the Contacts list. Fliqr AI generates a CSV containing all visible columns, including system fields, CUFs, and tags.
  </Step>
</Steps>

<Note>
  Contacts from different channels are merged into a single record when the same phone number or email address is detected. If a WhatsApp contact later messages via email using the same address, their history and fields are combined automatically.
</Note>

<Warning>
  Deleting a contact is permanent. The contact's conversation history, field values, and tags are removed and cannot be recovered. Archive or tag contacts as `inactive` instead of deleting them if you may need the data later.
</Warning>

## What's next

<CardGroup cols={2}>
  <Card title="Automation Rules" icon="bolt" href="/docs/core-concepts/automation-rules">
    Trigger Flows automatically when a tag is applied, a field value changes, or a keyword is received.
  </Card>

  <Card title="Flows" icon="diagram-project" href="/docs/core-concepts/flows">
    Build conversation scripts that capture data into the Custom User Fields you have just defined.
  </Card>
</CardGroup>