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

# Contact List

> Organize and manage contact groups for targeted messaging and campaigns

## Overview

Contact Lists allow you to organize contacts into groups for targeted messaging, scheduled campaigns, and broadcast communications. Create, manage, and maintain lists of contacts with support for bulk operations and dynamic list management.

## Key Features

* **List Management**: Create and organize multiple contact lists
* **Bulk Operations**: Add or remove multiple contacts at once
* **Contact Metadata**: Store contact names and additional information
* **Dynamic Updates**: Add/remove contacts anytime
* **Scheduler Integration**: Use lists with scheduled messages
* **Broadcast Support**: Send messages to entire lists
* **List Analytics**: Track list size and engagement

## How It Works

1. **Create List**: Define a new contact list with name and description
2. **Add Contacts**: Populate list with phone numbers and names
3. **Manage Contacts**: Add or remove contacts as needed
4. **Use in Campaigns**: Reference list in scheduled messages or broadcasts
5. **Monitor Performance**: Track delivery and engagement metrics

## List Structure

### Basic List

```json theme={null}
{
  "name": "VIP Customers",
  "description": "High-value customers for exclusive offers",
  "contacts": [
    {
      "remoteJid": "5511999999999@s.whatsapp.net",
      "pushName": "John Doe"
    },
    {
      "remoteJid": "5511888888888@s.whatsapp.net",
      "pushName": "Jane Smith"
    }
  ]
}
```

### Contact Format

Each contact requires:

* **remoteJid**: WhatsApp ID (phone number + @s.whatsapp.net)
* **pushName**: Display name (optional but recommended)

## List Operations

### Creating Lists

Create a new contact list with initial contacts:

```json theme={null}
POST /contact-list/create/{instance}
{
  "name": "Newsletter Subscribers",
  "description": "Users subscribed to weekly newsletter",
  "contacts": [
    {
      "remoteJid": "5511999999999@s.whatsapp.net",
      "pushName": "Alice Johnson"
    }
  ]
}
```

### Adding Contacts

Add new contacts to existing list:

```json theme={null}
POST /contact-list/addContacts/:contactListId/{instance}
{
  "contacts": [
    {
      "remoteJid": "5511777777777@s.whatsapp.net",
      "pushName": "Bob Wilson"
    },
    {
      "remoteJid": "5511666666666@s.whatsapp.net",
      "pushName": "Carol Martinez"
    }
  ]
}
```

### Removing Contacts

Remove specific contacts from list:

```json theme={null}
POST /contact-list/removeContacts/:contactListId/{instance}
{
  "remoteJids": [
    "5511999999999@s.whatsapp.net",
    "5511888888888@s.whatsapp.net"
  ]
}
```

### Updating List Details

Update list name or description:

```json theme={null}
PUT /contact-list/update/:contactListId/{instance}
{
  "name": "Premium Subscribers",
  "description": "Updated description"
}
```

## Use Cases

### Marketing Campaigns

Segment customers by interest, purchase history, or demographics for targeted campaigns.

### Newsletter Distribution

Maintain subscriber lists for regular newsletter delivery.

### Event Invitations

Create lists for event attendees and send invitations or updates.

### Customer Segments

Organize customers by tier (VIP, regular, new) for differentiated messaging.

### Geographic Targeting

Group contacts by region for location-specific communications.

### Product-Specific Lists

Maintain lists of customers interested in specific products or services.

### Loyalty Programs

Manage members of loyalty or rewards programs.

### Support Groups

Organize customers by support tier or issue type.

## Integration with Scheduler

Use contact lists with scheduled messages:

```json theme={null}
POST /scheduler/create/{instance}
{
  "name": "Monthly Newsletter",
  "contactListId": "list-123",
  "content": {
    "text": "Hello! Here's your monthly update..."
  },
  "runAt": "2024-03-01T09:00:00Z"
}
```

Benefits:

* Send to entire list with one schedule
* Automatic handling of list changes
* Unsubscribe management per list
* Delivery tracking per list

## List Management Best Practices

### Organization

1. **Clear Naming**: Use descriptive, consistent names
2. **Detailed Descriptions**: Document list purpose and criteria
3. **Regular Cleanup**: Remove inactive or invalid contacts
4. **Segmentation**: Create focused lists rather than large general lists
5. **Duplicate Prevention**: Check for duplicates before adding

### Data Quality

1. **Validate Numbers**: Ensure phone numbers are correctly formatted
2. **Update Names**: Keep contact names current
3. **Remove Bounces**: Remove numbers that consistently fail
4. **Consent Tracking**: Only include contacts who opted in
5. **Privacy Compliance**: Follow data protection regulations

### Performance

1. **List Size**: Keep lists manageable (recommend \< 10,000 contacts)
2. **Batch Operations**: Use bulk add/remove for efficiency
3. **Regular Updates**: Keep lists current with recent data
4. **Archive Old Lists**: Remove or archive unused lists

## Advanced Features

### List Merging

Combine multiple lists into one:

1. Export contacts from source lists
2. Deduplicate contacts
3. Create new merged list
4. Verify and test

### List Splitting

Divide large lists into smaller segments:

* By engagement level
* By geographic region
* By customer tier
* Random sampling for A/B testing

### Dynamic Lists

(Coming soon) Auto-update lists based on criteria:

* Recent purchases
* Activity level
* Customer attributes
* Behavioral triggers

## Analytics & Insights

Track list performance:

* **List Size**: Total contacts in list
* **Growth Rate**: New contacts over time
* **Churn Rate**: Contacts removed or unsubscribed
* **Engagement**: Message open and response rates
* **Delivery Success**: Percentage of successful deliveries
* **Unsubscribe Rate**: Opt-out percentage

## Compliance & Privacy

### Data Protection

* **GDPR Compliance**: Right to be forgotten, data portability
* **Consent Management**: Only include opted-in contacts
* **Data Security**: Secure storage and transmission
* **Access Control**: Limit who can view/modify lists
* **Audit Trail**: Track all list modifications

### Opt-Out Management

Respect unsubscribe requests:

1. Remove from all relevant lists
2. Block from future additions
3. Log unsubscribe event
4. Confirm removal to user

### WhatsApp Policies

* Only message contacts who opted in
* Respect WhatsApp's messaging limits
* Avoid spam or excessive messaging
* Follow WhatsApp Business Policy

## Import & Export

### Import Contacts

Import from CSV or JSON:

```csv theme={null}
phone,name
5511999999999,John Doe
5511888888888,Jane Smith
```

Convert to API format and bulk add.

### Export Contacts

Export list for backup or analysis:

1. Retrieve full list via API
2. Convert to desired format
3. Store securely
4. Use for reporting or migration

## Error Handling

### Common Issues

* **Invalid Phone Numbers**: Validate format before adding
* **Duplicate Contacts**: Check before adding to prevent duplicates
* **List Not Found**: Verify list ID before operations
* **Permission Denied**: Ensure proper authentication
* **Rate Limits**: Batch operations may hit rate limits

### Best Practices

1. Validate input before API calls
2. Handle errors gracefully
3. Retry failed operations
4. Log errors for debugging
5. Provide user feedback

## Getting Started

### Quick Start Guide

1. **Create Your First List**

```json theme={null}
POST /contact-list/create/{instance}
{
  "name": "Test List",
  "description": "My first contact list",
  "contacts": []
}
```

2. **Add Contacts**

```json theme={null}
POST /contact-list/addContacts/:contactListId/{instance}
{
  "contacts": [
    {
      "remoteJid": "5511999999999@s.whatsapp.net",
      "pushName": "Test Contact"
    }
  ]
}
```

3. **Use in Schedule**

```json theme={null}
POST /scheduler/create/{instance}
{
  "contactListId": "your-list-id",
  "content": { "text": "Hello!" },
  "runAt": "2024-03-15T10:00:00Z"
}
```

4. **Monitor Results**

```json theme={null}
GET /contact-list/find/:contactListId/{instance}
```

## Example Workflows

### Newsletter Management

```json theme={null}
// 1. Create subscriber list
POST /contact-list/create/{instance}
{
  "name": "Newsletter Subscribers",
  "contacts": []
}

// 2. Add new subscriber
POST /contact-list/addContacts/:listId/{instance}
{
  "contacts": [{
    "remoteJid": "5511999999999@s.whatsapp.net",
    "pushName": "New Subscriber"
  }]
}

// 3. Schedule newsletter
POST /scheduler/create/{instance}
{
  "contactListId": "list-id",
  "content": { "text": "Newsletter content..." },
  "runAt": "2024-03-15T09:00:00Z"
}

// 4. Handle unsubscribe
POST /contact-list/removeContacts/:listId/{instance}
{
  "remoteJids": ["5511999999999@s.whatsapp.net"]
}
```

For detailed API documentation, see the API Reference section.