Contact List - ZapThinker API Documentation

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

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

List Structure

Basic List

{
  "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:

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:

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:

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

Updating List Details

Update list name or description:

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. 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:

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

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

Data Quality

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

Performance

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

Advanced Features

List Merging

Combine multiple lists into one:

Export contacts from source lists
Deduplicate contacts
Create new merged list
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:

Remove from all relevant lists
Block from future additions
Log unsubscribe event
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:

phone,name
5511999999999,John Doe
5511888888888,Jane Smith

Convert to API format and bulk add.

Export Contacts

Export list for backup or analysis:

Retrieve full list via API
Convert to desired format
Store securely
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

Validate input before API calls
Handle errors gracefully
Retry failed operations
Log errors for debugging
Provide user feedback

Getting Started

Quick Start Guide

Create Your First List

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

Add Contacts

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

Use in Schedule

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

Monitor Results

GET /contact-list/find/:contactListId/{instance}

Example Workflows

// 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.

Getting Started

Documentation Index

​Overview

​Key Features

​How It Works

​List Structure

​Basic List

​Contact Format

​List Operations

​Creating Lists

​Adding Contacts

​Removing Contacts

​Updating List Details

​Use Cases

​Marketing Campaigns

​Newsletter Distribution

​Event Invitations

​Customer Segments

​Geographic Targeting

​Product-Specific Lists

​Loyalty Programs

​Support Groups

​Integration with Scheduler

​List Management Best Practices

​Organization

​Data Quality

​Performance

​Advanced Features

​List Merging

​List Splitting

​Dynamic Lists

​Analytics & Insights

​Compliance & Privacy

​Data Protection

​Opt-Out Management

​WhatsApp Policies

​Import & Export

​Import Contacts

​Export Contacts

​Error Handling

​Common Issues

​Best Practices

​Getting Started

​Quick Start Guide

​Example Workflows

​Newsletter Management

Overview

Key Features

How It Works

List Structure

Basic List

Contact Format

List Operations

Creating Lists

Adding Contacts

Removing Contacts

Updating List Details

Use Cases

Marketing Campaigns

Newsletter Distribution

Event Invitations

Customer Segments

Geographic Targeting

Product-Specific Lists

Loyalty Programs

Support Groups

Integration with Scheduler

List Management Best Practices

Organization

Data Quality

Performance

Advanced Features

List Merging

List Splitting

Dynamic Lists

Analytics & Insights

Compliance & Privacy

Data Protection

Opt-Out Management

WhatsApp Policies

Import & Export

Import Contacts

Export Contacts

Error Handling

Common Issues

Best Practices

Getting Started

Quick Start Guide

Example Workflows

Newsletter Management