WhatsApp API

Overview

This document describes the WhatsApp messaging API functionality provided by the Unecast platform. The API supports sending various types of WhatsApp messages including text, images, documents, and template messages.

Message Types

The API supports the following message types:

Text Messages

Simple text messages with optional preview URL support.

Template Messages

Pre-approved WhatsApp business template messages with dynamic content support.

Image Messages

Image messages with optional captions.

Document Messages

Document sharing with automatic filename detection and optional captions.

API Endpoints

Send Message v2

Endpoint (POST): https://api.unecast.com/v2/send

Description: Sends a message via WhatsApp channel

Request Schema

Required Fields

Field	Type	Description	Validation
to	string/array	Recipient phone number(s)	Max 18 characters
from	string	Sender ID	Max 18 characters

Optional Fields

Field	Type	Description	Validation	Default
channel	string	Communication channel	Must be 'sms' or 'whatsapp'	-
message	string	Message content	Required when no template_id	-
priority	number	Message priority	0-3 (0=lowest, 3=highest)	0
media_url	string	Media file URL	Valid URI format	-
template_id	string	WhatsApp template ID	-	-
template_data	object	Template parameters	Only allowed with template_id	-

Validation Rules

Recipient (to)

• Single recipient: String with max 18 characters

• Multiple recipients: Array of strings, minimum 1 recipient

• Format: Phone numbers without special characters

Message Content

• With template_id: Message is optional

• Without template_id: Message is required

• Cannot be empty when required

Priority Levels

• 0: Lowest priority (default)

• 1: Low priority

• 2: High priority

• 3: Highest priority

Channel

• Must be either "sms" or "whatsapp"

• Case-sensitive validation

Response Format

Success Response

{
  "status": "success",
  "message": "Message sent successfully",
  "code":200,
  "data": [{
      "message_id": "c19d896841ee247b",
      "message_count": 1,
      "from": "15551377539",
      "to": "94766354698",
      "message": "Your Message Here",
      "timestamp": "2025-10-19T06:45:31.571Z"
    }]
}

Error Response

{
  "status": "error",
  "message": "Error description",
  "code": 400,
  "data": {
    // API response data
  } 
}

Examples

1

Send Simple Text Message

Request:

POST /v2/send
Content-Type: application/json

{
  "from": "YourBrand",
  "to": "1234567890",
  "channel": "whatsapp",
  "message": "Hello! Welcome to our service.",
  "priority": 1
}

2

Send Template Message

Request:

POST /v2/send
Content-Type: application/json

{
  "from": "YourBrand",
  "to": "1234567890",
  "channel": "whatsapp",
  "template_id": "welcome_template",
  "template_data": {
    "name": "welcome_template",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "John Doe"
          }
        ]
      }
    ]
  }
}

3

Send Image Message

Request:

POST /v2/send
Content-Type: application/json

{
  "from": "YourBrand",
  "to": "1234567890",
  "channel": "whatsapp",
  "message": "Check out our new product!",
  "media_url": "https://example.com/product-image.jpg",
  "template_data": {
    "type": "image"
  }
}

4

Send Document

Request:

POST /v2/send
Content-Type: application/json

{
  "from": "YourBrand",
  "to": "1234567890",
  "channel": "whatsapp",
  "message": "Here's your requested document",
  "media_url": "https://example.com/invoice.pdf",
  "template_data": {
    "type": "document"
  }
}

5

Send to Multiple Recipients

Request:

POST /v2/send
Content-Type: application/json

{
  "from": "YourBrand",
  "to": ["1234567890", "0987654321", "1122334455"],
  "channel": "whatsapp",
  "message": "Broadcast message to multiple recipients",
  "priority": 2
}

Technical Implementation Notes

HTTP Client Fallback System

1

Primary: Axios HTTP client

2

Fallback 1: cURL (Unix/Linux systems)

3

Fallback 2: PowerShell (Windows systems)

4

Fallback 3: wget (Unix/Linux systems)

Document Filename Detection

When sending documents, the system automatically:

• Extracts filename from the provided URL

• Adds default .pdf extension if no extension is detected

• Uses "document.pdf" as fallback filename

Template Language Support

• Default language: "en_US"

• Supports custom language codes in template data

• Language code format follows WhatsApp Business API standards

Message Length Limitations

The API enforces different message length limits based on the message type and content:

WhatsApp Text Messages

Message Type	Character Limit	Notes
Standard Text Messages	4,096 characters	For regular text messages without templates
Media Messages (Image/Document)	1,024 characters	For captions with image or document attachments
Template Messages	No enforced limit	Template messages bypass character count restrictions

SMS Messages

Message Type	Character Limit	Notes
Standard SMS	No Limit ( Recommended 1,600 characters)	Automatically split into multiple SMS parts
GSM Character Set	Variable	Uses GSM character counting algorithm

Implementation Details

Character Counting Algorithm

The system uses getCharCount() from GSM Character Utils which:

• Counts characters using GSM 7-bit encoding rules

• Calculates message segments for SMS delivery

• Handles special characters and Unicode properly

Message Segmentation

SMS Segmentation

• Single SMS: Up to 160 GSM characters or 70 Unicode characters

• Multi-part SMS: Automatically split by the system

• Message Count: Calculated using charCount.msgCount

• Maximum Limit: 1,600 characters total across all segments

WhatsApp Segmentation

• Single Message: Always counted as 1 message regardless of length

• No Auto-splitting: Messages are sent as single units

• Media Messages: Image/document messages with captions count as 1 message

Error Messages

Length-Related Errors

Error Message	Trigger Condition	Solution
"WhatsApp message content cannot exceed 4096 characters. Please shorten your message or use a template."	WhatsApp text message > 4,096 characters	Reduce message length or use template
"WhatsApp media captions cannot exceed 1024 characters. Please shorten your caption."	WhatsApp media caption > 1,024 characters	Reduce caption length

Best Practices for Message Length

WhatsApp Best Practices

• Keep text messages under 4,096 characters for optimal delivery

• Limit media captions to 1,024 characters to avoid rejection

• Use templates for longer content to bypass length restrictions

• Consider user experience — shorter messages are more readable

SMS Best Practices

• Stay under 160 characters to avoid message splitting costs

• Use GSM character set when possible to maximize character count

• Monitor message count for billing and delivery optimization

• Consider concatenated SMS limits for longer messages

Template Message Best Practices

• No character limits apply to approved WhatsApp business templates

• Template parameters can contain longer content

• Use templates for consistent, longer messaging scenarios

Character Set Considerations

GSM 7-bit Character Set

• Standard characters: A-Z, a-z, 0-9, basic punctuation

• Extended characters: €, [, ], {, }, , ^, ~, | (count as 2 characters)

• Optimal for SMS: Maximizes character count per message segment

Unicode (UCS-2) Character Set

• All languages supported: Including emoji, special symbols

• Reduced capacity: 70 characters per SMS segment

• WhatsApp friendly: Full Unicode support without penalties

Integration Notes

The message length validation is implemented in the sendV2Messages function within smsServiceV2.js and occurs before message queuing. This ensures:

• Early validation prevents invalid messages from entering the system

• Clear error messages help developers understand limitations

• Service-specific rules are enforced based on the delivery channel

• Template bypass allows flexible content for approved templates

Rate Limiting and Best Practices

• Message Priority: Use priority levels appropriately to ensure important messages are delivered first

• Media URLs: Ensure media URLs are publicly accessible and properly formatted

• Phone Numbers: Always validate phone numbers before sending

• Template Messages: Use approved WhatsApp Business templates only

• Error Handling: Implement proper error handling for all API calls

---

Last Updated: October 19, 2025 API Version: v2 Document Version: 1.1