# Contacts & Groups

## Overview

Contacts is your workspace address book — every person you can message, with their name, phone number, email, language, groups, and an internal memo. Groups are the segments you sort contacts into (VIP customers, new signups, cart abandoners, and so on) so you can target broadcasts, WhatsApp campaigns, catalog sends, and flow enrolment at exactly the right audience.

Open it from the top navigation under Contacts. The page has a side rail of views and group filters, a four-tile stat row, and a searchable contacts table that switches between list and grid. A Groups view on the same page lists your groups with live member counts.

What | Detail
--- | ---
Where to find it | Top navigation → Contacts (and the Groups view)
Who can open it | Workspace role Manager or above. Agents and Viewers do not see this page.
Page size | Contacts show 12 per page.
Visibility | Shared by the whole workspace — a teammate sees contacts a colleague added or imported.
Isolation | Each workspace only ever sees its own contacts and groups.

> Shared by workspace: contacts and groups belong to the workspace, not to the person who created them. The only exception is older records imported before workspaces existed — those stay visible to their original owner until re-imported.

## Prerequisites

Contacts has no external credentials — you can start adding people immediately. Two things govern how many you can hold and what you can do with them:

Requirement | Where it comes from
--- | ---
Manager role | Your workspace owner sets your role under Team Inbox → Members. Manager (or Admin/Owner) is required to reach Contacts.
Contacts plan limit | Your plan sets how many contacts you can hold. View your plan and usage under Account → Plans; the limit applies to both adding one contact and importing a file.
A connected number (to actually message) | Optional for storing contacts, required for sending. Connect one under Devices. Keep numbers in international format so messaging works straight away.

> Plan limit: if your workspace is already at its contacts limit, adding or importing contacts is blocked until you upgrade or remove some. The check runs before a contact is created and before an import begins.

## Adding a contact

1. Click Add contact (top right) to open the contact modal.
2. Fill in at least a first name and a mobile number (the only required fields).
3. Optionally set a country code, email, language, one or more groups, an address, an internal memo, and an avatar image.
4. Click save. The contact appears at the top of the table (newest first).

### Field reference

Field | Required | Limit / rule | Notes
--- | --- | --- | ---
First name | Yes | Max 191 chars | Used to build the display name when you don't set one explicitly.
Title | No | Max 50 chars | Optional honorific (Mr, Dr, ...).
Middle name | No | Max 191 chars | Combined into the display name.
Last name | No | Max 191 chars | Combined into the display name.
Name (full) | No | Max 191 chars | If set, used verbatim as the display name; otherwise WaDesk joins title + first + middle + last.
Mobile | Yes | Max 32 chars | The WhatsApp number. If a country code is set and the number doesn't already start with it, the code is prepended automatically.
Country code | No | Max 10 chars | Dialling prefix such as `91` or `1`.
Email | No | Max 191, validated | Must be a valid email address.
Language | No | Max 80 chars | Preferred language / locale.
Groups | No | Existing group IDs | One or more groups to file this contact under. Each must already exist in the workspace.
Address | No | Max 1000 chars | Freeform address.
Memo | No | Max 2000 chars | Internal note shown in the Memo column.
Image | No | Image, max 2 MB | Optional avatar.
Unsubscribed | No | On / off | Marks the contact as opted out. Counts toward the Unsubscribed stat.

> How the display name is built: if you fill the full Name field it wins. Otherwise WaDesk joins whichever of title, first name, middle name, and last name are present, separated by spaces.

## Importing contacts from CSV

Click Bulk upload to import a CSV file. WaDesk uses a two-step, preview-first flow so you never import blind.

### Step by step

1. Choose a file. Pick a `.csv` file (max 5 MB).
2. Review the auto-mapping. WaDesk reads the header row, auto-detects which column maps to which field, and shows the first five data rows so you can confirm the mapping looks right.
3. Set "apply to all rows" defaults (optional). Choose a Status, a Source, a Group, and Tags to stamp onto every imported row (see the table below for how each is stored).
4. Import. Submit the file again. Each valid row becomes a contact and you get a summary: "Imported N contacts (M skipped)."

### Column auto-detection

Header names are normalised before matching — lowercased with all non-alphanumeric characters stripped — so `Phone Number`, `phone_number`, and `PHONE-NUMBER` all resolve to the same field. The first header that matches a field wins. These are the exact recognised names:

Field | Recognised header names (after normalisation)
--- | ---
Name | `name`, `full name`, `contact name`, `first name`
Last name | `last name`, `surname`, `family name`
Mobile | `mobile`, `phone`, `phone number`, `whatsapp`, `whatsapp number`, `number`, `tel`, `telephone`, `cell`, `cellphone`, `msisdn`
Email | `email`, `email address`, `mail`
Country code | `country code`, `cc`, `dial code`
Group | `group`, `groups`, `contact group`, `list`, `lists`
Language | `language`, `lang`, `locale`

### How rows are processed

- A row is skipped if it has no name or no mobile. The skipped count is reported in the summary.
- On import, the imported name is stored as both the full name and the first name; map a last name column if you want surnames split out.
- A CSV Group column can name multiple groups, comma-separated. Each name is matched case-insensitively against existing workspace groups; any that doesn't exist yet is created for you, scoped to the workspace.
- The CSV's own group column takes precedence; the "apply to all rows" group is merged in as a fallback so contacts always land in at least that group.

### What the "apply to all rows" knobs do

Knob | How it is stored
--- | ---
Group | Added to each contact's groups (on top of any groups from the CSV).
Status | Saved on each contact so campaigns can filter by it.
Source | Saved on each contact so you can tell where they came from.
Tags | Tags applied to every imported contact.

> File requirements: CSV only, max 5 MB. Keep phone numbers in international format with the country code so messaging works straight away. Your contacts limit is checked before the import runs — a workspace already at the limit is blocked.

## Groups (segments)

Groups are how you slice your audience. Click New group to create one.

1. Give the group a name (required).
2. Optionally add a note and pick a colour.
3. Save. The group appears in the left rail and in the Groups view with a live member count.

Field | Required | Limit | Notes
--- | --- | --- | ---
Name | Yes | Max 191 chars | Shown on the group chip everywhere the group appears.
Note | No | Max 500 chars | A short description of who's in the group.
Colour | No | Max 32 chars | Renders as a coloured dot on the group chip.

- Switch to the Groups view to see every group with its current member count.
- Editing a group lets you rename it, change its note, or change its colour.
- Deleting a group first removes it from every contact that's in it, then removes the group itself. The contacts are kept — they simply lose that one group.

> Why groups matter: broadcasts, WhatsApp campaigns, catalog sends, and flow enrolment all target by group. Member counts are always calculated fresh, so they're accurate rather than out of date.

## Searching, filtering & the stat row

The contacts table has its own controls:

- Search by name, email, or phone — filtering happens live as you type.
- Side-rail views: All contacts, Groups, Imported (contacts brought in via CSV), and No group (contacts not in any segment).
- Group filters: click any group in the left rail to show only its members.
- List / grid toggle switches the table between a dense list and a card grid.

The stat row at the top always shows four workspace-wide counts:

Stat | Counts
--- | ---
Total contacts | Every contact in the workspace.
Groups | Number of groups defined.
Subscribed | Contacts not marked unsubscribed.
Unsubscribed | Contacts marked opted out.

## Editing and deleting

Each row has an edit icon (opens the contact in a modal) and a delete icon (asks to confirm). To remove several at once, tick the checkboxes and use Delete selected.

1. Edit: open the row, change any field, save. The same name-building and country-code-prepend rules from Adding a contact apply on update.
2. Single delete: click the delete icon and confirm.
3. Bulk delete: select rows and choose Delete selected.

> Deletion is permanent. Both single and bulk deletes only affect your current workspace, so you can never delete a contact in another workspace. Deleting a contact removes them from this workspace's address book — it does not erase past conversation history in the inbox, but the contact will no longer appear in pickers, segments, or campaign audiences.

## Troubleshooting

Symptom | Cause & fix
--- | ---
"Add contact" / "Bulk upload" is blocked | You're at your plan's contacts limit. Remove contacts or upgrade under Account → Plans.
Import skipped many rows | Those rows had no name or no mobile value. Check your header names against the auto-detection table and that those columns are filled in.
Phone column not detected | Rename the header to one of the recognised names (e.g. `mobile`, `phone`, `whatsapp`, `msisdn`). Matching ignores case and punctuation but the word itself must match.
Numbers don't message correctly | Store them in full international format. Either include the country code in the number, or add a country-code column / field so WaDesk can add it.
Group from CSV created a duplicate | Group matching ignores capitalisation, so `VIP` and `vip` become one group. A genuinely new name is created on purpose — tidy up in the Groups view.
File rejected on upload | It must be a CSV under 5 MB. Export from your spreadsheet as `.csv` (not `.xlsx`).
Can't reach Contacts at all | Your workspace role is Agent or Viewer. Ask the owner to raise it to Manager under Team Inbox → Members.