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

# How Convo Manages WhatsApp Contacts and Attributes

> Contacts represent your WhatsApp subscribers. Learn how Convo stores contact data, supports custom attributes, and manages opt-in status.

A **Contact** in Convo is a record that represents a single WhatsApp user who has interacted with — or been added to — your Project. Each Contact stores identity information, engagement state, custom attributes, and opt-in preferences. Keeping your Contact data accurate ensures your campaigns reach the right people and your automations trigger correctly.

> [!NOTE]
>
> All phone numbers in Convo must include the country code **without** a leading `+`. For example, an Indian mobile number `+91 70893 79345` should be stored as `917089379345`.

***

## Contact Fields

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique Convo identifier for this Contact. |
| `phone_number` | string | The contact's WhatsApp number including country code (e.g., `917089379345`). |
| `name` | string | Display name of the contact. |
| `country_code` | string | The numeric country code extracted from `phone_number` (e.g., `91`). |
| `on_whatsapp` | boolean | Whether this number is a registered WhatsApp account. |
| `tags` | array of strings | Labels assigned to this contact for segmentation and filtering. |
| `attributes` | object | Custom key-value pairs for storing additional contact metadata. |
| `is_closed` | boolean | Whether the contact's chat has been marked as resolved/closed. |
| `is_intervened` | boolean | Whether a human agent has taken over the conversation from the chatbot. |
| `is_requesting` | boolean | Whether the contact is in the requesting queue awaiting agent assistance. |
| `last_active` | ISO 8601 datetime | Timestamp of the contact's most recent activity. |
| `created_at` | ISO 8601 datetime | Timestamp when this Contact record was created in Convo. |

***

## Opt-in & Consent

WhatsApp's commerce and messaging policies require that contacts have consented to receive messages from your business before you send them outbound communications.

* **New contacts** added via the Convo API or imported through the dashboard should only be added once you have obtained explicit opt-in consent from the user.
* If a contact requests to opt out or stop receiving messages, you should refrain from including them in future campaigns and remove them from your active contact lists accordingly.
* Convo's dashboard provides tools for managing contact segments and campaign audience filters, allowing you to honour opt-out requests by excluding specific contacts or tags from sends.

***

## Tags

Tags are plain-text labels that you attach to contacts for segmentation. They let you group contacts by behaviour, lifecycle stage, campaign source, or any other dimension your business needs.

* A contact can hold **multiple tags** simultaneously (stored as an array of strings).
* Tags are **case-insensitive** and trimmed of leading/trailing whitespace on save.
* You can filter Broadcast campaign audiences and trigger automation flows based on tag membership.

**The `first_message` tag** is a system-generated tag automatically applied to a contact the very first time they message your WhatsApp number. You can use this tag in automations to trigger welcome flows or onboarding sequences for brand-new contacts.

***

## Custom Attributes

The `attributes` object is a flexible key-value store attached to every contact. You can use it to persist any custom data you need alongside the contact record.

```json theme={null}
{
  "attributes": {
    "order_id": "ORD-98765",
    "membership_tier": "gold",
    "crm_id": "SF-00112233",
    "preferred_language": "hi"
  }
}
```

Common use cases include:

| Use Case | Example Key | Example Value |
| - | - | - |
| CRM reference | `crm_id` | `"SF-00112233"` |
| Order tracking | `order_id` | `"ORD-98765"` |
| Loyalty / membership | `membership_tier` | `"gold"` |
| Personalisation | `preferred_language` | `"hi"` |
| Subscription status | `subscription_active` | `"true"` |

Attribute values are always stored as **strings**. When you read them back, cast to the appropriate type in your application code. You can reference attributes dynamically inside chatbot flows and template parameters.

***

## Chat States

Convo tracks the current state of a contact's conversation using three boolean flags. These are particularly important when you combine the API with a live-agent or chatbot setup.

| Flag | Meaning |
| - | - |
| `is_closed` | The conversation has been marked as **resolved** by an agent or automation. No further chatbot responses will be triggered until the chat is reopened. |
| `is_intervened` | A **human agent has taken over** the conversation from the chatbot. The bot will stay silent until the agent releases control. |
| `is_requesting` | The contact is in the **requesting queue** — the chatbot could not handle the query and has escalated it, but no agent has picked it up yet. |

These flags work together. A typical escalation flow looks like:

**1. Chatbot handles the conversation**

`is_intervened: false`, `is_requesting: false`, `is_closed: false`

**2. Chatbot cannot answer — contact is queued**

`is_requesting: true` — the contact awaits a human agent.

**3. Agent picks up the conversation**

`is_intervened: true`, `is_requesting: false` — the agent is now in control.

**4. Agent resolves the conversation**

`is_closed: true`, `is_intervened: false` — the chat is resolved.


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