Channels

Introduction to WhatsApp Channels

WhatsApp Channels is a powerful broadcasting platform that allows organizations, businesses, and individuals to share updates, news, and content with their audience. Through this API, you can programmatically manage channels, making it easier to integrate WhatsApp Channels into your applications and workflows.

Key Features

Channel Ownership: Create and manage your own channels
Content Publishing: Share various types of content (text, media, links)
Subscription Management: Allow users to follow/unfollow channels
Analytics: Track channel performance and engagement
Automation: Integrate with your existing systems and workflows

Use Cases

News organizations broadcasting updates
Businesses sharing product launches and promotions
Community groups disseminating information
Educational institutions sharing announcements
Content creators engaging with their audience

Best Practices

1. Content Strategy

Plan your content calendar
Maintain consistent posting schedule
Mix different content types
Include engaging captions
Use high-quality media
2. Technical Implementation
Always include channel JID in requests
Validate media formats and sizes
Implement proper error handling
Monitor API rate limits
Cache channel information when appropriate

3. Channel Management

Keep channel information updated
Monitor engagement metrics
Respond to subscriber feedback
Maintain content quality
Regular channel health checks

Channel Lifecycle

Understanding the lifecycle of a WhatsApp Channel is crucial for effective management. Here's how channels work from creation to ongoing management:

1. Channel Creation

The first step in the channel lifecycle is creation. You'll need to provide basic information about your channel:

{
  "name": "string", // Required: Channel name
  "description": "string", // Optional: Channel description
  "picture": "string" // Optional: Base64-encoded channel picture
}

Endpoint: POST /newchannel

Example:

curl -X POST http://localhost:8888/newchannel \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Zanzibar Travel Adventures",
    "description": "Discover the magic of Zanzibar! Get exclusive travel offers, insider tips, and breathtaking moments from the Spice Island.",
    "picture": {
      "picurl": "https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg"
    }
  }'

Response:

{
  "id": "120363417316079578",
  "state": "ACTIVE",
  "metadata": {
    "name": "Zanzibar Travel Adventures",
    "description": "Discover the magic of Zanzibar! Get exclusive travel offers, insider tips, and breathtaking moments from the Spice Island.",
    "creation_time": "2024-03-18T12:34:56Z"
  },
  "viewer_info": {
    "viewer_count": 0,
    "subscriber_count": 0
  }
}

2. Channel Information Management

Once created, you can retrieve and monitor your channel's information:

Endpoint: GET /getchannelinfo

Retrieves current channel metadata
Useful for monitoring channel status
Helps verify channel settings

Example request:

curl "http://localhost:8888/getchannelinfo?channel=120363417316079578"

Example response:

{
  "id": "120363417316079578@newsletter",
  "state": {
    "type": "active"
  },
  "thread_metadata": {
    "creation_time": "1742778261",
    "invite": "0029VbAZOHUInlqIYvFQI03M",
    "name": {
      "text": "Zanzibar Travel Adventures",
      "id": "1742778261155474",
      "update_time": "1742778261155474"
    },
    "description": {
      "text": "Discover the magic of Zanzibar with exclusive travel packages, stunning visuals, and insider tips for your perfect island getaway.",
      "id": "1742778261155474",
      "update_time": "1742778261155474"
    },
    "subscribers_count": "1",
    "verification": "unverified",
    "picture": {
      "url": "",
      "id": "1742780634582507",
      "type": "IMAGE",
      "direct_path": ""
    },
    "preview": {
      "url": "",
      "id": "1742780634582508",
      "type": "PREVIEW",
      "direct_path": ""
    },
    "settings": {
      "reaction_codes": {
        "value": "ALL"
      }
    }
  },
  "viewer_metadata": {
    "mute": "on",
    "role": "owner"
  }
}

The response includes:

Channel ID and state
Creation time and invite link
Channel name and description
Subscriber count
Verification status
Channel picture and preview information
Channel settings
Viewer metadata (mute status and role)

Publishing Content

Channels thrive on regular content updates. You can publish various types of content:

Endpoint: POST /channelpublish

Supported content types:

Text messages
Example:

curl -X POST http://localhost:8888/channelpublish \
  -H "Content-Type: application/json" \
  -d '{
    "jid": "120363417316079578@newsletter",
    "text": "New updates coming in less than 1h, stay tunned"
  }'

Response:

Text message published successfully

Images

Example:

curl -X POST http://localhost:8888/channelpublish \
  -H "Content-Type: application/json" \
  -d '{
    "jid": "120363417316079578@newsletter",
    "image": {
      "url": "https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg"
    },
    "caption": "🌴 Welcome to Zanzibar Travel Adventures! Experience the magic of pristine beaches, crystal-clear waters, and rich cultural heritage. Stay tuned for exclusive offers and travel tips!"
  }'

Response:

Media message published successfully

Video

Example:

curl -X POST http://localhost:8888/channelpublish \
  -H "Content-Type: application/json" \
  -d '{
    "jid": "120363417316079578@newsletter",
    "image": {
      "url": "https://file-examples.com/storage/fe93592a2667e462d9964f3/2017/04/file_example_MP4_480_1_5MG.mp4"
    },
    "caption": "Travel around the globe with us. Pick your spot!"
  }'

Response:

Media message published successfully

Documents

Example:

curl -X POST http://localhost:8888/channelpublish \
  -H "Content-Type: application/json" \
  -d '{
    "jid": "120363417316079578@newsletter",
    "image": {
      "url": "https://pdfobject.com/pdf/sample.pdf"
    },
    "caption": "Check out your travel options in our brochure."
  }'

Response:

Media message published successfully

Link with preview

Example:

curl -X POST http://localhost:8888/channelpublish \
  -H "Content-Type: application/json" \
  -d '{
    "jid": "120363417316079578@newsletter",
    "link": {
        "title": "Visit Zanzibar",
        "text": "Enjoy some great holidays at our island. Visit us on https://www.zanzibar.com/holidays",
        "url": "https://www.zanzibar.com/holidays",
        "thumbnail": "https://www.zanzibar.com/media-assets/zanzibar_brand_logo-400.png",
        "description": "Best place on earth to relax"
    }
  }'

Response:

Link message published successfully

Message History

Keep track of your channel's content history:

Endpoint: GET /getnewslettermessages

Main Functionality:

Retrieves messages from a WhatsApp newsletter/channel
Returns messages in chronological order (newest first)
Supports pagination through the before parameter

Parameters:

Parameter	Type	Required	Description
`channelJID`	string	Yes	The newsletter's JID (e.g., "120363417316079578@newsletter")
`count`	integer	No	Number of messages to retrieve (default: 50)
`before`	integer	No	Message server ID to get messages before

Example Usage:

# Get latest 50 messages
curl "http://localhost:8888/getnewslettermessages?channelJID=120363417316079578@newsletter"

# Get 25 messages
curl "http://localhost:8888/getnewslettermessages?channelJID=120363417316079578@newsletter&count=25"

# Get messages before a specific server ID
curl "http://localhost:8888/getnewslettermessages?channelJID=120363417316079578@newsletter&before=123456789"

Endpoint: GET /getnewslettermessageupdates

Main Functionality:

Retrieves updates (like view counts, reaction counts) for newsletter messages
Can get updates for specific messages or within a time range
Useful for tracking message engagement

Parameters:

Parameter	Type	Required	Description
`channelJID`	string	Yes	The newsletter's JID (e.g., "120363417316079578@newsletter")
`count`	integer	No	Number of updates to retrieve
`since`	string	No	ISO 8601 timestamp to get updates since (e.g., "2024-03-20T00:00:00Z")
`after`	integer	No	Message server ID to get updates after

Example Usage:

# Get latest updates
curl "http://localhost:8888/getnewslettermessageupdates?channelJID=120363417316079578@newsletter"

# Get updates from last 24 hours
curl "http://localhost:8888/getnewslettermessageupdates?channelJID=120363417316079578@newsletter&since=$(date -v-24H -u +"%Y-%m-%dT%H:%M:%SZ")"

# Get updates after a specific message
curl "http://localhost:8888/getnewslettermessageupdates?channelJID=120363417316079578@newsletter&after=123456789"

# Combine parameters
curl "http://localhost:8888/getnewslettermessageupdates?channelJID=120363417316079578@newsletter&count=20&since=$(date -v-12H -u +"%Y-%m-%dT%H:%M:%SZ")&after=123456789"

Important Notes:

Both endpoints require a valid channelJID parameter
Message server IDs (before and after parameters) must be numeric values
The since parameter must be in ISO 8601 format (RFC3339)
The count parameter must be a positive integer
Both endpoints return JSON responses
Error responses include appropriate HTTP status codes and descriptive messages

Common Use Cases:

Fetching initial messages from a newsletter
Implementing pagination to load older messages
Tracking message engagement through updates
Monitoring newsletter activity within specific time periods
Combining both endpoints to get both messages and their engagement metrics

Subscription Management

Following Channels

Subscribe to channels to receive updates and notifications:

Endpoint: GET /follow?channel=<channel_id>

Main Functionality:

Enables subscription to channel updates
Users receive notifications for new content
Returns success/failure status of the subscription

Parameters:

Parameter	Type	Required	Description
`channel`	string	Yes	The channel's JID (e.g., "120363417316079578@newsletter")

Example Usage:

# Subscribe to a channel
curl "http://localhost:8888/follow?channel=120363417316079578@newsletter"

Response:

Success: HTTP 200 with success message
Error: HTTP 400 if channel ID is invalid or missing
Error: HTTP 500 for server-side issues

Unfollowing Channels

Unsubscribe from channels to stop receiving updates:

Endpoint: GET /unfollow?channel=<channel_id>

Main Functionality:

Removes subscription from a channel
Stops receiving channel updates and notifications
Returns success/failure status of the unsubscription

Parameters:

Parameter	Type	Required	Description
`channel`	string	Yes	The channel's JID (e.g., "120363417316079578@newsletter")

Example Usage:

# Unsubscribe from a channel
curl "http://localhost:8888/unfollow?channel=120363417316079578@newsletter"

Response:

Success: HTTP 200 with success message
Error: HTTP 400 if channel ID is invalid or missing
Error: HTTP 500 for server-side issues

Managing Subscriptions

View and manage your channel subscriptions:

Endpoint: GET /following

Example Usage:

# Get list of subscribed channels
curl "http://localhost:8888/following"

Response Format:

[
  {
    "id": "120363417316079578@newsletter",
    "state": {
      "type": "active"
    },
    "thread_metadata": {
      "creation_time": "1742778261",
      "invite": "0029VbAZOHUInlqIYvFQI03M",
      "name": {
        "text": "Zanzibar Travel Adventures",
        "id": "1742778261155474",
        "update_time": "1742778261155474"
      },
      "description": {
        "text": "Discover the magic of Zanzibar with exclusive travel packages, stunning visuals, and insider tips for your perfect island getaway.",
        "id": "1742778261155474",
        "update_time": "1742778261155474"
      },
      "subscribers_count": "0",
      "verification": "unverified",
      "picture": {
        "url": "",
        "id": "1743118574758421",
        "type": "IMAGE",
        "direct_path": ""
      },
      "preview": {
        "url": "",
        "id": "1743118574758422",
        "type": "PREVIEW",
        "direct_path": ""
      },
      "settings": {
        "reaction_codes": {
          "value": "ALL"
        }
      }
    },
    "viewer_metadata": {
      "mute": "on",
      "role": "owner"
    }
  }
]

Important Notes:

All endpoints require an authenticated WhatsApp session
Channel JIDs must be in the correct format (ending with @newsletter)
The /following endpoint returns an empty list if no channels are subscribed
Error responses include appropriate HTTP status codes and descriptive messages

Common Use Cases:

Subscribing to new channels
Managing notification preferences
Cleaning up unused subscriptions
Monitoring subscription status
Building a channel management interface

Introduction to WhatsApp Channels​

Key Features​

Use Cases​

Best Practices​

Channel Lifecycle​

1. Channel Creation​

2. Channel Information Management​

Publishing Content​

Message History​

Main Functionality:​

Parameters:​

Example Usage:​

Main Functionality:​

Parameters:​

Example Usage:​

Important Notes:​

Common Use Cases:​

Subscription Management​

Following Channels​

Main Functionality:​

Parameters:​

Example Usage:​

Response:​

Unfollowing Channels​

Main Functionality:​

Parameters:​

Example Usage:​

Response:​

Managing Subscriptions​

Example Usage:​

Response Format:​

Important Notes:​

Common Use Cases:​

Introduction to WhatsApp Channels

Key Features

Use Cases

Best Practices

Channel Lifecycle

1. Channel Creation

2. Channel Information Management

Publishing Content

Message History

Main Functionality:

Parameters:

Example Usage:

Main Functionality:

Parameters:

Example Usage:

Important Notes:

Common Use Cases:

Subscription Management

Following Channels

Main Functionality:

Parameters:

Example Usage:

Response:

Unfollowing Channels

Main Functionality:

Parameters:

Example Usage:

Response:

Managing Subscriptions

Example Usage:

Response Format:

Important Notes:

Common Use Cases: