# Contacts

> Every phone number that has messaged your WhatsApp number - searching, filtering, tags and categories, profiles, and jumping to a contact's conversation or calls.

Source: https://docs.theavoxai.com/contacts

Contacts lists every phone number that has exchanged messages with your connected WhatsApp number. You
never build this list by hand: Avox adds a contact automatically the first time a number messages you,
calls you, or arrives in your imported chat history.

The page header reads "Your customers' phone numbers are encrypted at rest and only ever visible to
your account." and has a **Docs** button that opens this page.

Under the header, two tabs switch between **Contacts** (the list) and **Tags & categories** (see
[Tags and categories](#tags-and-categories)).

## Who can use Contacts

| Action | Admin | Manager |
| --- | --- | --- |
| View and search contacts | Yes | Yes |
| Rename a contact | Yes | Yes |
| Add or remove tags and categories, edit profile details | Yes | Yes |
| Create, rename, recolour and delete tags and categories | Yes | Yes |
| See full phone numbers | Yes | No (last 4 digits only) |

The Manager column shows the defaults. An Admin can change them for each person in **Settings >
Switchboard > Members > Permissions** (the **See contacts**, **Edit contacts** and **See full phone
numbers** permissions). See [Permissions](https://docs.theavoxai.com/switchboard/members#permissions).

Contacts needs a WhatsApp connection. Until your Switchboard has one, the **Contacts** item in the
sidebar (under **Messaging**) shows a lock, and hovering it shows "Contacts is locked" with "This
feature needs a WhatsApp connection first." ([AVX-3001](https://docs.theavoxai.com/error-codes/avx-3001)). Opening the
Contacts address takes you to [Connections](https://docs.theavoxai.com/connections).

## How contacts are created

A contact is created for a phone number the first time any of these happens:

- The number sends a message to your WhatsApp number.
- The number calls your WhatsApp number, or you call it (with [Calling](https://docs.theavoxai.com/connections/calling) turned
  on).
- The number appears in the chat history or contact list imported from the WhatsApp Business app. See
  [Coexistence sync](https://docs.theavoxai.com/connections/coexistence).

Each phone number appears once per Switchboard, however many messages it sends.

## Count tiles

Tiles across the top of the page count your contacts:

| Tile | What it counts |
| --- | --- |
| **Total contacts** | Every contact in this Switchboard. |
| **New this week** | Contacts added in the last 7 days. |
| **New this month** | Contacts added in the last 30 days. |
| **Active in last 7 days** | Contacts with at least one message, sent or received, in the last 7 days. |
| **Uncategorised** | Contacts that aren't in any category yet. |
| One tile per category | Your 4 biggest categories, each with how many contacts are in it. With more than 4, a **+N more** tile opens the full list in the Segments sidebar. |

Click a tile to show just those contacts. The tile stays highlighted and the filter shows above the
table; click the tile again, the small x on the filter, or **Clear all** to go back to everyone.

## Segments

The **Segments** sidebar on the left lists **All contacts**, then every **category** (with its colour
and how many contacts are in it), every **tag**, and **Uncategorised**. Click one to show only those
contacts. On a phone, tap the button next to the search box (it shows the segment you're in) to open
the same list.

The segment you're in is part of the page address, so you can bookmark or share it, and your
browser's back button returns to the previous one. When you open a contact from a segment, their
profile shows a **Back to** link (for example "Back to VIP") that returns you to the same list and
page.

On a wide screen, the button left of the search box hides or shows the sidebar. Avox remembers your
choice on that device.

## The contacts table

Contacts are listed with the most recently changed first. Each row shows:

| Column | What it shows |
| --- | --- |
| (checkbox) | Select the contact for a bulk change - see [Changing several contacts at once](#changing-several-contacts-at-once). |
| **Name** | The contact's avatar and name, with their categories and tags underneath (up to 3, then "+2"). With no name saved, the phone number shows instead, or "Unknown contact". |
| **Phone number** | The full phone number in international format, digits only - if you have the **See full phone numbers** permission. Without it you see only the last 4 digits, like •••• 4821. |
| **Location** | The location your team entered on the profile, if any. Otherwise the country from the number's country code, plus the place from the last location the customer shared on WhatsApp. |
| **Last activity** | How long ago the contact's record last changed ("just now", "5m ago", "3h ago", or a date). |
| **Actions** | **Profile**, **Message** and **Calls** - see [Row actions](#row-actions). |

Click anywhere on a row (or select it with **Tab** and press **Enter**) to open that contact's
[profile](#the-customer-profile). The checkbox, the rename pencil and the buttons in the row do their
own thing instead.

Each contact has a generated avatar, so the same customer has the same avatar everywhere in Avox:
here, on their profile, in the Inbox and on Calls. See [Contact avatars](#contact-avatars).

The table shows 25 contacts per page. When you have more, the footer shows "Page 1 of 4 · 92
contacts" with **Previous** and **Next** buttons.

With no contacts yet, the table reads "No contacts yet." An empty segment reads, for example,
"Nothing in VIP yet." with **Show all contacts**.

## Filtering by tags and categories

Use the **Category** and **Tags** buttons next to the search box. Each opens a list you can search;
tick as many as you like. The table then shows contacts that have any of the ticked categories **and**
any of the ticked tags. The chosen tags and categories show above the table; click the small x on one
to drop it, or **Clear all** to drop every filter. Filters work together with the search box and the
count tiles.

## Changing several contacts at once

Tick the checkbox on the rows you want (the checkbox in the header ticks every contact on the page).
A bar appears with:

- **Add tags or categories** - pick tags or categories to add to every selected contact. Type a new
  name to create it on the spot.
- **Remove tags or categories** - pick tags or categories to take off every selected contact.
- **Clear selection**.

This works inside a segment too. If the change moves contacts in or out of the segment you're in (for
example, removing the category you're looking at), the list refreshes to match.

Up to 200 contacts can be changed at once. A contact can have at most 50 tags and categories;
anything over that is skipped and a note says so.

## Renaming a contact

The name you set here is the name your whole team sees across the dashboard - in the [Inbox](https://docs.theavoxai.com/inbox),
on [Calls](https://docs.theavoxai.com/calls), and on [Overview](https://docs.theavoxai.com/overview).

**1. Find the contact**

Search for them, or page through the table.

**2. Click the pencil**

Hover the name and click the pencil icon next to it. The name turns into a text box.

**3. Type the new name and save**

Type up to 120 characters, then click the check mark. The new name shows straight away, and the
[Avox Avatar](https://docs.theavoxai.com/avox-avatar) says "Renamed."

To remove a saved name, clear the box and save. The table then shows the phone number instead. A name
longer than 120 characters shows "Keep it under 120 characters" under the box.

> **Note**
>
> When your number is connected with Coexistence, contact names saved in the WhatsApp Business app on
> your phone also sync into Avox. When a contact is added or edited in the app's contact list, Avox
> picks up that name. See [Coexistence sync](https://docs.theavoxai.com/connections/coexistence).

If the name doesn't save, you see "Couldn't save that contact's name. Try again."
([AVX-3062](https://docs.theavoxai.com/error-codes/avx-3062)). Check your connection and try again.

## Row actions

- **Profile** opens the contact's [profile](#the-customer-profile).
- **Message** opens this contact's conversation in the [Inbox](https://docs.theavoxai.com/inbox).
- **Calls** opens [Calls](https://docs.theavoxai.com/calls) filtered to this contact. Calls shows call history once
  [Calling](https://docs.theavoxai.com/connections/calling) is turned on for your connection.

## Searching

Type in **Search by name or phone number** and press **Enter**. The search works in two ways:

- **Names** - type part of a name. "mar" finds "Maria" and "Omar".
- **Phone numbers** - type the **whole** number, including the country code. Spaces, dashes, brackets
  and a leading `+` are ignored, so `+1 (555) 123-4567` and `15551234567` find the same contact.
  Anything with 6 or more digits is treated as a phone number search.

A phone number search looks for an exact match of the full number. To find someone by a few digits,
search by their name instead, or type the full number.

If nothing matches, the table reads "No contacts match these filters." To see everyone again, click
the small x on the search above the table, or clear the box and press **Enter**.

> **Tip**
>
> In the Inbox, **Profile** in the chat header shows the contact's key details, with **Open full
> profile** to come here. You can also link to a search directly: `/contacts?q=maria`.

## Tags and categories

Tags and categories help your team group and find customers. Customers never see them.

- A **category** says what kind of customer someone is, like Lead, Customer or Supplier. Categories
  show as filled, rounded rectangles, and use a folder icon everywhere in Avox.
- A **tag** marks anything else worth knowing, like vip or follow-up. A contact can have many. Tags
  show as pills with a coloured dot, and use a tag icon everywhere in Avox.

Open the **Tags & categories** tab to manage them. Each list shows every tag or category with how
many contacts have it, and "12 of 500" at the top (you can have up to 500 of each).

- **New category** / **New tag** - give it a name (up to 40 characters), pick a colour, and
  optionally a short description of when to use it. Names are unique per kind, ignoring capitals: "VIP"
  and "vip" count as the same tag, while a tag and a category can share a name.
- **Colour** - one of 11 palette colours, or **Custom colour**: type a hex code (like `#2f7d56`), use
  your browser's colour picker, or pick a suggested colour. Any colour works - the text colour adjusts
  so it stays readable.
- **Avatar shape** (categories only, optional) - pick one of ten shapes (Round, Organic, Boxy,
  Capsule, Nub, Cloud, Droplet, Hexagon, Sun, Triangle) to give every contact in the category that
  avatar shape, or keep "Each contact's own shape". A preview shows the avatar in the category's
  colour. See [Contact avatars](#contact-avatars).
- The pencil renames, recolours, or changes the description or avatar shape. A renamed tag updates on
  every contact straight away.
- The bin deletes the tag or category after you confirm. It's removed from every contact that had it;
  this can't be undone.

You can add and remove tags and categories on a contact's profile, in the [Inbox](https://docs.theavoxai.com/inbox) chat
header, or on many contacts at once from the list. In each place, typing a name that doesn't exist
yet offers **Create tag "..."** or **Create category "..."** with a colour pick.
[Automations](https://docs.theavoxai.com/automation) can add them too.

> **Note**
>
> Older automations that tag contacts keep working: their tags appear here as regular tags.

## Contact avatars

Every contact gets a small generated character as their avatar - the same family as the
[Avox Avatar](https://docs.theavoxai.com/avox-avatar). It's made for that contact and stays the same everywhere in Avox. Its
look follows your tags and categories:

- **Colour** - the colour of the contact's first category (in alphabetical order). With no category,
  the colour of their first tag. With neither, Avox green.
- **Shape** - the **Avatar shape** chosen for that first category. Without one, each contact keeps
  their own shape.
- **Mood** - it reacts to the contact's activity:

| The avatar looks | When |
| --- | --- |
| Surprised | A brand-new contact, first seen in the last 24 hours. |
| Sleepy | No messages either way for 30 days or more. |
| Thinking | Waiting for your reply - their message is the latest one. |
| Happy | They messaged in the last 24 hours and you replied. |
| Neutral | Anything else. |

So a category such as "VIP" with its own colour and shape makes those customers easy to spot at a
glance in the Inbox, on Calls and here.

## The customer profile

Click a contact (or **Profile**) to open their profile. Under the page title, a **Back to** link
returns you to the list you came from, with the same segment, filters and page (or "Back to all
contacts"). At the top:

- Their avatar, name, number, country (from the number) and location, with **Message** (their
  conversation in the [Inbox](https://docs.theavoxai.com/inbox)) and **Calls** (their calls on [Calls](https://docs.theavoxai.com/calls)) on the right.
- Their **categories and tags**, with **Add category** and **Add tag** buttons. Click the x on a tag
  or category to remove it.
- Stat cards: first seen, last seen, messages (from them and from you), calls, Flow responses and
  automations run.

Below that, three tabs:

- **Timeline** - every message, call, Flow response and automation for this customer, newest first.
  Long timelines scroll inside their own box; **Load older activity** fetches more.
- **Chats** - the latest messages as a preview, with **Open in Inbox** to continue the conversation.
- **Calls** - their call history: who called, the outcome (connected, ended, missed), how long, and
  when, with **See all calls**.

On the side:

- **About** - location (city, state or region, country), gender and age. WhatsApp doesn't share any of
  these, so your team enters them with **Edit details**, or an automation collects them with an "Ask a
  question" step. The country from the customer's number is offered as the default. Gender is
  optional (Female, Male, Non-binary, Prefer not to say). For age, save either a birthday or an age
  range, not both. **Custom fields** shows answers your automations saved to the contact; you can edit
  them, remove them, or add your own (names use lowercase letters, numbers and underscores).
- **Notes**, **Shared locations** (places the customer sent on WhatsApp) and **Shared media and
  files**. Long lists scroll inside their own box.

## How phone numbers are protected

Every phone number is encrypted before it's stored, and it's decrypted only to show it to members of
your own Switchboard who have the **See full phone numbers** permission (Admins always do; everyone
else sees the last 4 digits). The same rule applies on a contact's profile page. Your contacts are
never visible to any other Avox account. This is also why a
phone number search needs the full number: Avox looks up the number as a whole rather than reading
through stored numbers. See [Security](https://docs.theavoxai.com/security).

## Errors on this page

| Message | Code | What to try |
| --- | --- | --- |
| Couldn't load your contacts. Try again. | [AVX-3063](https://docs.theavoxai.com/error-codes/avx-3063) | Refresh the page. If it keeps happening, contact [Support](https://docs.theavoxai.com/support). |
| Couldn't save that contact's name. Try again. | [AVX-3062](https://docs.theavoxai.com/error-codes/avx-3062) | Check the name is 120 characters or fewer, then save again. |