> ## Documentation Index
> Fetch the complete documentation index at: https://help.messagesync.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Understanding WhatsApp Contact Tags

## Summary[​](#summary "Direct link to Summary")

**Automatic Tags Added by the System:**

| Tag                               | When Added              | Purpose                                          |
| --------------------------------- | ----------------------- | ------------------------------------------------ |
| `wa: +1234567890`                 | Every message           | Routes messages through specific WhatsApp number |
| `inbound whatsapp`                | First inbound message   | Identifies contacts who initiated conversation   |
| `fb-ad-lead-whatsapp`             | Facebook ad click       | Tracks Facebook ad attribution                   |
| `instagram-ad-lead-whatsapp`      | Instagram ad click      | Tracks Instagram ad attribution                  |
| `another-device-replied-whatsapp` | Reply from other device | Tracks multi-device usage                        |
| `whatsapp group`                  | Group member            | Identifies group contacts                        |

**Key Takeaways:**

* Tags are added automatically - no manual work required
* WhatsApp number tags ensure conversation continuity
* Source tags enable powerful attribution tracking
* Use tags for segmentation and targeted campaigns
* System maintains clean, accurate tags automatically

# Understanding WhatsApp Contact Tags

## Overview[​](#overview "Direct link to Overview")

Our WhatsApp integration automatically manages contact tags in your CRM to track message sources, WhatsApp number associations, and user interactions. This document explains what tags get added, when they get added, and why they're important for your business.

## Tag Categories[​](#tag-categories "Direct link to Tag Categories")

### 1. WhatsApp Number Association Tags[​](#1-whatsapp-number-association-tags "Direct link to 1. WhatsApp Number Association Tags")

**Format:** `wa: +1234567890`

**Purpose:** Track which WhatsApp phone number is associated with each contact for intelligent message routing.

**When Added:**

* When a contact sends their first message to your WhatsApp number (During contact creation from inbound messages)
* When you send a message to a contact from a specific WhatsApp number
* When manual override is used (`{WA#N}` pattern) to switch which number to use for a contact
* When you send a message via your phone directly to the contact.

**How It Works:**

* **Automatic Cleanup:** Old WhatsApp number tags are automatically removed when you use a different number
* **Single Active Tag:** Only one WhatsApp number tag exists per contact at any time
* **Smart Routing:** Future messages to this contact will automatically use the tagged number

**Example:**

```text theme={null}
Contact initially has: "wa: +12125551234"You send a message from: +19175559999 (via phone)Contact now has: "wa: +19175559999" (old tag automatically removed)
```

**Why This Matters:**

* Maintains conversation continuity with the same number
* Prevents confusion for your contacts
* Ensures consistent sender identity
* Enables intelligent routing of outbound messages

***

### 2. Message Source Tags[​](#2-message-source-tags "Direct link to 2. Message Source Tags")

#### 2.1 Inbound WhatsApp Tag[​](#21-inbound-whatsapp-tag "Direct link to 2.1 Inbound WhatsApp Tag")

**Tag:** `inbound whatsapp`

**Purpose:** Identify contacts who initiated the conversation by messaging you first.

**When Added:**

* Automatically applied when a new contact sends their first WhatsApp message to you
* Only added once when the contact is created

**Why This Matters:**

* **Segmentation:** Easily filter contacts who reached out to you vs. those you contacted first
* **Lead Quality:** Inbound contacts often indicate higher intent and engagement
* **Automation:** Trigger specific workflows for inbound vs. outbound contacts

***

#### 2.2 Click-to-WhatsApp (CTWA) Source Tags[​](#22-click-to-whatsapp-ctwa-source-tags "Direct link to 2.2 Click-to-WhatsApp (CTWA) Source Tags")

**Tags:**

* `fb-ad-lead-whatsapp` - Contact came from Facebook Ads
* `instagram-ad-lead-whatsapp` - Contact came from Instagram Ads

**Purpose:** Track which advertising platform drove the WhatsApp conversation.

**When Added:**

* Automatically detected when someone clicks your Facebook or Instagram ad and starts a WhatsApp conversation
* Applied when the contact is created or sends their first message

**Why This Matters:**

* **Attribution:** Know exactly which ad campaign generated each lead
* **ROI Tracking:** Measure return on investment per advertising platform
* **Budget Optimization:** Identify which platform drives better engagement
* **Campaign Analysis:** Compare Facebook vs. Instagram performance
* **Retargeting:** Create custom audiences based on ad source

**Example Ad Context:**

When someone clicks your ad, they might see this information in the ad:

```text theme={null}
Ad Title: "Start Your US Company From Anywhere"Description: "Register in Hours with Legal LLC!"Platform: Facebook
```

This information helps you understand what messaging resonated with the contact.

***

### 3. Interaction Tags[​](#3-interaction-tags "Direct link to 3. Interaction Tags")

#### 3.1 Another Device Replied Tag[​](#31-another-device-replied-tag "Direct link to 3.1 Another Device Replied Tag")

**Tag:** `another-device-replied-whatsapp`

**Purpose:** Track when you or your team replies to a contact from a device other than your CRM (like WhatsApp mobile app or WhatsApp Web).

**When Added:**

* Automatically applied when a message is sent from another WhatsApp device
* Added each time a reply is sent outside the CRM

**Why This Matters:**

* **Stop AI Bot:** Stop AI bot auto replies during manual intervention
* **Multi-Channel Tracking:** Understand when team members use WhatsApp directly

**Example Scenarios:**

* Sales rep responds urgently from their phone
* Support team member handles escalation via WhatsApp Web
* After-hours emergency response from mobile device

***

### 4. Group-Related Tags[​](#4-group-related-tags "Direct link to 4. Group-Related Tags")

#### 4.1 WhatsApp Group Tag[​](#41-whatsapp-group-tag "Direct link to 4.1 WhatsApp Group Tag")

**Tag:** `whatsapp group`

**Purpose:** Identify contacts that are used as proxy for Whatsapp Groups. These contacts would contain the Group's conversation.

**When Added:**

* When you add a WhatsApp group to your allowed groups

**Why This Matters:**

* **Segmentation:** Separate group members from individual contacts
* **Compliance:** Ensure group messaging follows regulations
* **Targeting:** Create group-specific campaigns or exclude groups from broadcasts

***

## Tag Usage in Message Routing[​](#tag-usage-in-message-routing "Direct link to Tag Usage in Message Routing")

### How Tags Control Message Routing[​](#how-tags-control-message-routing "Direct link to How Tags Control Message Routing")

Tags play a crucial role in determining which WhatsApp number sends messages to your contacts:

**Contact Tag Routing (Priority 2 in our routing system):**

When a contact has a WhatsApp number tag (`wa: +1234567890`), the system will:

* Always use that specific WhatsApp number for outbound messages
* Maintain conversation continuity
* Ensure consistent sender identity
* Show an error if that number is disconnected

**Benefits:**

* **Conversation Continuity:** Contacts always see the same number responding to them
* **Relationship Building:** Consistent identity builds trust
* **Manual Control:** You can override which number to use manually
* **Predictable Routing:** Know exactly which number will be used

**Error Handling:**

If the tagged number is not connected, you'll see:

```text theme={null}
Error 104: Whatsapp number +12125551234 is not connected.Either connect the number or remove the tag "wa:+12125551234" from the contact!
```

***

## Tag Analytics & Reporting[​](#tag-analytics--reporting "Direct link to Tag Analytics & Reporting")

### Useful Segments and Reports[​](#useful-segments-and-reports "Direct link to Useful Segments and Reports")

**Track Ad Campaign Performance:**

Create a segment with tag `fb-ad-lead-whatsapp` to:

* Calculate conversion rate from Facebook ads
* Measure revenue attribution per platform
* Compare ad creative performance
* Optimize ad spend based on results

**Measure Inbound Engagement:**

Create a segment with tag `Inbound Whatsapp` to:

* Track first response time for inbound leads
* Measure conversation quality and length
* Calculate inbound lead conversion rate
* Identify best-performing inbound sources

**Monitor Multi-Device Usage:**

Create a segment with tag `another-device-replied-whatsapp` to:

* Calculate manual intervention rate
* Identify contacts requiring personal attention
* Track team member response patterns
* Measure automation effectiveness

**Group Messaging Insights:**

Create a segment with tag `whatsapp group` to:

* Track group engagement metrics
* Analyze group vs. individual performance
* Optimize group communication strategy

***

## Support[​](#support "Direct link to Support")

If you need help with the setup or onboarding:

* Email: [**support@messagesync.ai**](mailto:support@messagesync.ai)