# 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 ```json { "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 ```json { "status": "error", "message": "Error description", "code": 400, "data": { // API response data } } ``` ## Examples {% stepper %} {% step %} ### Send Simple Text Message Request: ```json POST /v2/send Content-Type: application/json { "from": "YourBrand", "to": "1234567890", "channel": "whatsapp", "message": "Hello! Welcome to our service.", "priority": 1 } ``` {% endstep %} {% step %} ### Send Template Message Request: ```json 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" } ] } ] } } ``` {% endstep %} {% step %} ### Send Image Message Request: ```json 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" } } ``` {% endstep %} {% step %} ### Send Document Request: ```json 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" } } ``` {% endstep %} {% step %} ### Send to Multiple Recipients Request: ```json POST /v2/send Content-Type: application/json { "from": "YourBrand", "to": ["1234567890", "0987654321", "1122334455"], "channel": "whatsapp", "message": "Broadcast message to multiple recipients", "priority": 2 } ``` {% endstep %} {% endstepper %} ## Technical Implementation Notes ### HTTP Client Fallback System {% stepper %} {% step %} Primary: Axios HTTP client {% endstep %} {% step %} Fallback 1: cURL (Unix/Linux systems) {% endstep %} {% step %} Fallback 2: PowerShell (Windows systems) {% endstep %} {% step %} Fallback 3: wget (Unix/Linux systems) {% endstep %} {% endstepper %} ### 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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developer.unecast.com/rest-api/whatsapp-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.