Skip to main content
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

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.
Common use cases include: 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. 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.