> ## Documentation Index
> Fetch the complete documentation index at: https://doc.convo.co.in/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.
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:
`is_intervened: false`, `is_requesting: false`, `is_closed: false`
`is_requesting: true` — the contact awaits a human agent.
`is_intervened: true`, `is_requesting: false` — the agent is now in control.
`is_closed: true`, `is_intervened: false` — the chat is resolved.