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)

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

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
}

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"
          }
        ]
      }
    ]
  }
}

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"
  }
}

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"
  }
}

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

Primary: Axios HTTP client

Fallback 1: cURL (Unix/Linux systems)

Fallback 2: PowerShell (Windows systems)

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

PreviousREST API NextSMS API

Last updated 6 days ago

Was this helpful?