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

# Contacts Overview

> Your customer database inside Xobito — add, segment, and target the people you message on WhatsApp.

Your **Contacts** module is where every person you communicate with on WhatsApp lives. It is a lightweight CRM that powers the rest of Xobito — campaigns, chatbots, live chat, and automations all pull from this single list.

## Why contacts matter

Every WhatsApp message you send is tied to a contact. A clean contact list means:

* **Higher delivery rates** — valid numbers with country codes go through every time.
* **Better targeting** — groups, statuses, and sources let you send the right message to the right people.
* **Personalised messages** — custom field values get merged into templates at send time.
* **Clearer reporting** — campaign analytics are split by status, source, and group.

## What you can do

<CardGroup cols={2}>
  <Card title="Add a contact" icon="user-plus" href="/contacts/add-contact">
    Create a single contact manually.
  </Card>

  <Card title="Import from CSV" icon="file-csv" href="/contacts/import-csv">
    Upload a small spreadsheet to add many contacts at once.
  </Card>

  <Card title="Organise into groups" icon="users" href="/contacts/groups">
    Named collections like "VIP Customers" — a contact can belong to unlimited groups.
  </Card>

  <Card title="Track status" icon="circle-dot" href="/contacts/statuses">
    One colour-coded label per contact — e.g. "Hot lead", "Customer".
  </Card>

  <Card title="Track source" icon="tag" href="/contacts/sources">
    One source per contact — where they came from.
  </Card>

  <Card title="Custom fields" icon="file-pen" href="/contacts/custom-fields">
    Add your own data points — text, number, date, dropdown, checkbox, textarea.
  </Card>
</CardGroup>

## The contact record

Every contact in Xobito has the following fields:

### Required

* **First Name** (`firstname`) — up to 191 characters.
* **Last Name** (`lastname`) — up to 191 characters.
* **Phone** — must be in E.164 format with a leading `+` and country code (e.g. `+14155551234`). Unique within your workspace.
* **Type** — each contact is either a `lead` or a `customer`. (An internal `guest` type is also used by some chat channels.)
* **Status** — one status from your [status library](/contacts/statuses).
* **Source** — one source from your [source library](/contacts/sources).

### Optional

* **Email** — if provided, must be unique within your workspace.
* **Company**, **Website**, **Description**.
* **Country**, **City**, **State**, **ZIP**, **Address**.
* **Assigned Agent** — a staff user responsible for the contact.
* **Groups** — a contact can belong to unlimited groups.
* **Custom fields** — any fields you define.

### Opt-out tracking

Each contact has an opted-out flag for tracking purposes. Automatic opt-out detection and campaign exclusion are not currently implemented — agents must manually disable contacts you no longer want to message. Roadmap item.

<Note>
  The phone number is the unique identifier for a contact. Two contacts cannot share the same phone number in the same workspace.
</Note>

## How contacts flow through Xobito

Contacts power the rest of the platform:

| Where contacts are used | What happens                                                       |
| ----------------------- | ------------------------------------------------------------------ |
| **Campaigns**           | Choose groups (or all contacts) as the audience of a broadcast.    |
| **Live Chat**           | Incoming WhatsApp messages auto-create or update a contact.        |
| **Bot Flows**           | A chatbot can write answers back into the contact's custom fields. |
| **Template Bots**       | Scheduled templates go out to a filtered segment.                  |
| **Reports**             | Analytics are broken down by status, source, and group.            |

## Typical workflow

<Steps>
  <Step title="Set up your library first">
    Create the **statuses**, **sources**, and **custom fields** you want to use. Xobito does not ship pre-seeded statuses or sources — you define them to match your business.
  </Step>

  <Step title="Add or import contacts">
    Add a few manually to test, then import the rest from CSV in small batches.
  </Step>

  <Step title="Organise into groups">
    Create groups for the audiences you'll send campaigns to.
  </Step>

  <Step title="Use them everywhere">
    Select groups in campaigns, reference custom fields in templates, and watch each contact's history grow as messages flow in and out.
  </Step>
</Steps>

## Kanban view

The Contacts page has a **Kanban view** in addition to the standard list view — useful for moving contacts through a pipeline visually.

### How it works

* Each column on the board is one of your [Contact Statuses](/contacts/statuses).
* Each card is a contact, showing name, phone, and key details.
* **Drag a card** from one column to another to change that contact's status. Dropping a Kanban card immediately updates the contact's status and `last_status_change` timestamp. The change is also captured in Activity Log. *(Outbound webhooks do not fire for status changes — only on contact create/update/delete.)*

### Permissions

* Staff with the `tenant.contact.view` permission see every contact on the board.
* Staff with only `tenant.contact.view_own` see just the contacts assigned to them — the columns still show, but with a filtered set of cards.

<Note>
  The Kanban view mirrors the list — every contact you would see in the list also appears on the board. To search or filter contacts, use the list view; the Kanban is designed for drag-and-drop status changes, not filtering.
</Note>

## Export to CSV

You can export your contact list as a CSV file at any time.

<Steps>
  <Step title="Open the Contacts list">
    Sidebar → **Contacts**.
  </Step>

  <Step title="Select contacts">
    Tick the checkbox next to each contact you want to export, or tick the header checkbox to select the whole page.
  </Step>

  <Step title="Choose 'Export'">
    Pick **Export** from the bulk-action menu above the table.
  </Step>

  <Step title="Download the file">
    Your browser downloads a UTF-8 CSV. It includes headers, the selected contact rows, and a column for each of your [custom fields](/contacts/custom-fields).
  </Step>
</Steps>

<Tip>
  The file is UTF-8 with a byte-order mark, so accented names and non-Latin scripts open correctly in Excel, Numbers, and Google Sheets.
</Tip>

<Note>
  Exporting requires the `tenant.contact.view` permission (or `tenant.contact.view_own` — in which case only your assigned contacts are included).
</Note>

## Good to know

<AccordionGroup>
  <Accordion title="Always use E.164 phone numbers">
    Numbers must start with `+` and a country code — `+14155551234`, `+447911123456`, `+919876543210`. A number without a country code will be rejected.
  </Accordion>

  <Accordion title="Every contact needs a status and a source">
    Status and source are required. If you haven't created any yet, go to **Contacts → Status** and **Contacts → Source** before adding your first contact.
  </Accordion>

  <Accordion title="Groups are unlimited">
    Unlike status (one per contact) and source (one per contact), a contact can belong to any number of groups at the same time.
  </Accordion>

  <Accordion title="Respect opt-outs">
    When a contact asks to stop receiving messages, mark them opted-out immediately. Continuing to message opted-out users hurts your phone number's quality rating with Meta.
  </Accordion>

  <Accordion title="Xobito does not use 'tags'">
    If you've used other CRMs, you may be looking for tags. Xobito uses **groups**, **statuses**, **sources**, and **custom fields** instead — pick whichever fits your use case.
  </Accordion>
</AccordionGroup>

## Related reading

<CardGroup cols={2}>
  <Card title="Key Concepts" icon="lightbulb" href="/key-concepts">
    Understand how contacts, sessions, and templates fit together.
  </Card>

  <Card title="Create a Campaign" icon="bullhorn" href="/campaigns/create-campaign">
    Put your contact groups to work in a broadcast.
  </Card>
</CardGroup>