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

# Contacts

> Manage your contact database — add, import, filter, and act on customer records across every channel.

## What is this?

Contacts is the single database of every customer record in your workspace — with search, filters, labels, status, and per-contact actions like Assign, Chat, Block, and Delete.

![Full Contacts page](https://mintcdn.com/wabis/WS9kn1_MGeoTtoMA/images/contacts-overview-overview.png?fit=max\&auto=format\&n=WS9kn1_MGeoTtoMA\&q=85\&s=9664f8b9bd7b3a9766fba51e9d61e7f5)

## What can I do here?

* Search contacts (the search box filters by name/phone as you type)
* Filter by **Labels** and **Status** (Active, Blocked, Unsubscribed) from the toolbar dropdowns
* Open **Filters** for advanced search: Name, Email, Phone, Assigned Team Member, Custom Field + value, Source, and a created-date range
* Add a new contact with **Add Contact** (Name, Email, Phone, and a required consent confirmation)
* **Import** contacts from a CSV or XLSX file with a step-by-step wizard — map your columns, apply labels, choose how to handle duplicates, and import in the background
* **Check Import History** to see the status of background import jobs, and watch a running import in the progress panel in the corner of the screen
* **Export** all contacts (emailed to you as a file) or **Export Selected** for just the checked rows
* **Check phone number** — runs a background validation pass on phone numbers for the active channel
* **Fix Invalid Phone Numbers** — adds a country code to numbers marked **Invalid Country Code**, and merges the duplicates this uncovers
* From a contact's row menu: **View Contact** (opens the [Contact Profile](https://wabis.mintlify.site/workspace/contacts/contact-profile.md)), **Assign Contact** to a teammate, **Chat** (jumps to that contact's conversation in Inbox), **Block Contact** / **Unblock Contact**, and **Delete**
* Select multiple contacts to **Export Selected**, **Assign Label**, or **Delete Selected** in bulk

![Contacts — key controls](https://mintcdn.com/wabis/WS9kn1_MGeoTtoMA/images/contacts-overview-controls.png?fit=max\&auto=format\&n=WS9kn1_MGeoTtoMA\&q=85\&s=54bee77cd90700988f4b752fd239f4d6)

## How to use it

**1. Add a single contact**

Click **Add Contact**, fill in **Name** and **Phone** (pick the country code first), optionally **Email**, then check the consent confirmation box. The **Add** button stays disabled until all three — name, phone, and the consent checkbox — are filled in.

![The Add Contact dialog with Name, Email, Phone + country code selector, and the consent checkbox](https://mintcdn.com/wabis/WS9kn1_MGeoTtoMA/images/contacts-add-contact-dialog.png?fit=max\&auto=format\&n=WS9kn1_MGeoTtoMA\&q=85\&s=9f4cc65c1c9539901f0a6fa6a0e82001)

**2. Import contacts in bulk**

Click **Import** to open the **Import Contacts** wizard. It has five steps, shown along the top: **Upload**, **Map Columns**, **Enrich**, **Confirm**, and **Import**. See [Import contacts](#import-contacts) below.

**3. Track the import**

The import runs in the background — close the wizard and keep working. A progress panel in the corner of the screen shows **Importing contacts** while it runs and **Contact import finished** when it is done. Click **Check Import History** (or **Import history** in the wizard) to see each import job's status and retry a failed job.

**4. Act on a contact**

Click the **⋯** menu on any row to assign it to a teammate, jump into its conversation via **Chat**, or block/delete it. Use the checkboxes and the bulk action bar to label or delete several contacts at once.

## Import contacts

**1. Upload**

Read the notes at the top: supported formats are **.csv** and **.xlsx**, the required column is **Phone Number** (Name is recommended), phone numbers must include the country code (for example +1 or +91), and you can map your column headers in the next step. Click **Download Sample Template** if you want a ready-made file, then drag and drop your file or browse for it.

**2. Map Columns**

The wizard shows how many rows and columns it found, and lists each **File Column Header** with a **Destination Field**. It matches columns automatically (marked **Auto**), and each shows a sample value. Change a destination to **Name**, **Phone Number**, **Email**, **Label**, one of your existing custom fields, **New custom field (use header)** to create a field from the column header, or **Don't import**. A column must be mapped to **Phone Number** — **Continue to Enrich** stays disabled until one is mapped. If nothing is mapped to **Name**, the phone number is used as the contact name. A preview of the first rows is shown below.

**3. Enrich**

Under **Apply Labels**, choose labels to add to every contact in this import (in addition to any labels mapped from file columns). Under **Duplicate Handling**, choose how contacts with matching phone numbers are treated: **Skip duplicates (Recommended)** keeps existing contact data untouched, while **Update existing contacts** updates their details with the new values from your file and adds the labels.

**4. Confirm**

Review the **Import Configuration Summary** — file name, total rows, mapped columns, duplicate strategy, and labels applied — and the **Confirmed field mapping** table showing each file header, its target field, and whether it is **Mapped** or **Skipped**. Click **Start Import**.

**5. Import**

The import is queued and runs in the background. You can click **Run in background** and keep working, or watch the counts — **New**, **Updated**, **Skipped**, and **Failed** — update as rows are processed. When it finishes, click **Done**.

### Phone numbers and country codes

A phone number is stored as digits with its country code. A leading `+`, `00` or `0` is removed, and digits in other scripts (Arabic-Indic, Devanagari, Tamil, full-width) become ordinary digits. The number must read as a valid international number — **nothing is guessed**, so a country code is never added unless you choose it.

* A number that isn't valid keeps its digits and gets the label **Invalid Country Code**. **Nothing is sent to it** until it is fixed — a send is refused and the message is saved as failed.
* A valid number gets its country in the **Country Code** custom field and loses the label.
* For a WhatsApp contact, the phone is read-only in the inbox contact panel unless it carries **Invalid Country Code**.
* **Check phone number** (toolbar) re-checks the numbers for the active channel in the background.

#### Fix Invalid Phone Numbers

Local numbers (for example `9876543210`) usually fail because the country code is missing. To fix them in bulk:

1. Click **Fix Invalid Phone Numbers** in the toolbar.
2. Enter the **Country calling code to add** — digits only, for example `91` for India or `971` for the UAE.
3. Click **Fix numbers**. It removes any `+`, `00` or `0` at the start of every number marked **Invalid Country Code**, puts your code in front, and shows the result: how many were **fixed**, **cleaned but still invalid**, **skipped because the fixed number already belongs to another contact**, and **still invalid**. Numbers that are still invalid stay marked.

If some were skipped, click **Review and merge the skipped**. Each pair is the same person saved twice — once without the country code and once with it. Click **Merge** to move conversations, messages, notes and labels onto the contact that already has the number and remove the invalid one. The removed contact is recorded in the surviving contact's activity log, and the merge **can't be undone**.

> [!WARNING]
>
> A local number can also be a valid number of another country (for example `9544102909` reads as a Myanmar number), and the rule can't catch that. Use the right country code for all the numbers you fix at once.

### Over your contact limit

Your plan allows a set number of contacts. If your workspace holds more than that:

* **Import and export** are refused until you upgrade or remove contacts.
* If your platform owner has switched on **Block sending messages above the contact limit**, you also can't send messages — the Contacts table and the open conversation are frozen (still readable) behind a card that says **You're over your contact limit** with how many contacts you have against the limit. Messages and contacts still arrive.

Click **Upgrade plan** on the card (shown if you can manage plans), or ask your account owner to upgrade. Your data stays visible the whole time.

## Troubleshooting / Technical Notes

* **A message to a contact fails with an invalid country code.** The contact's number has no valid country code. Use **Fix Invalid Phone Numbers**, or edit the number.
* **Add Contact stays disabled.** All of these must be true: the consent checkbox is checked, a country code is selected, **Name** is filled in, and **Phone** is filled in. The button is also disabled briefly while a contact is being created.
* **The consent checkbox is mandatory when adding a contact.** Its wording is fixed: *"I confirm that we have obtained appropriate consent to send SMS, email, or other types of messages from contact(s) being created or imported in compliance with applicable laws and regulations."* If someone can't add a contact, check this box first. The import wizard has no consent checkbox, so make sure you have consent for the people in your file before you import it.
* **"Unsupported file type. Upload a .csv or .xlsx file."** The wizard only accepts .csv and .xlsx files. Save your spreadsheet in one of those formats and upload it again.
* **"The file could not be read."** The file is damaged or in an unexpected format. Download the sample template and compare, then try again.
* **"Continue to Enrich" is disabled.** No column is mapped to **Phone Number** yet. Choose that column in **Map Columns**.
* **Some rows were not imported.** Check the **Skipped** and **Failed** counts in the import progress. Skipped rows are contacts that already exist (when **Skip duplicates** is chosen). For failed rows, check that every row has a phone number with its country code, then use **Import history** to see the job and retry it.
* **"The import could not be started."** The upload didn't reach the queue. Go **Back** to **Confirm** and click **Start Import** again.
* **The Chat row action is disabled.** No WhatsApp channel is configured for the workspace, or the contact has no phone number.
* **The Assign Contact action is disabled.** It requires the `inbox:assign` permission.
* **Block Contact or Unblock Contact isn't shown.** It's only available for contacts on WhatsApp or Facebook. For other channels, such as Instagram and Web Chat, the option is hidden entirely.
* **The page says "Please select or create a channel first."** No active channel is selected. Go to [Channels](https://wabis.mintlify.site/workspace/channels/overview.md).
* **The page shows an upgrade message.** WhatsApp integration is blocked by your current plan.
* **Creating a contact fails.** The message from the server is shown when there is one, otherwise "Failed to create contact."
* **Export was started but nothing arrived.** Exports are emailed to you as a file when they finish. The page doesn't show a download link or an expected delivery time, so check your email and spam folder.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.