/api/v1/whatsapp/sendSend WhatsApp Template Message
Dispatch official Meta-approved WhatsApp Business templates, time-critical OTP authentication codes, rich media attachments (images/PDFs), and interactive call-to-action buttons directly to customer handsets worldwide with enterprise SLAs.
Message Lifecycle & Delivery Pipeline
When you invoke the /api/v1/whatsapp/send endpoint, Softymize processes your request through a multi-tier resilient infrastructure:
Validates your API Key, sanitizes phone number to E.164, and verifies template parameter schema.
Asynchronous Redis queues ensure sub-millisecond API response with rate limit protection & zero checkout latency.
Dispatched directly over dedicated Meta Cloud infrastructure to the recipient handset with zero intermediate brokers.
Real-time delivery (sent, delivered, read) receipts are fired to your servers with HMAC signatures.
Request Headers & Security
| Header | Type | Requirement | Description |
|---|---|---|---|
| X-Softymize-API-Key | string | Required | Your SHA-256 hashed workspace production key (starts with sft_live_). |
| Content-Type | string | Required | Must be application/json. |
| X-Idempotency-Key | string (UUID) | Optional | Unique request ID (e.g. ord_confirm_99182a). Prevents duplicate messaging if a client network retry occurs within 24 hours. |
Meta Template Categories & Approval Guidelines
Every outgoing WhatsApp message requires a pre-approved template registered under your Meta Business Account. Softymize automatically routes these through Meta based on category:
Order confirmations, shipping updates, payment receipts, delivery notifications. High deliverability and lowest Meta conversation fee.
Verification codes with native one-tap "Copy Code" button. Strict Meta security rules: zero promotional text or external hyperlinks allowed.
Abandoned cart recovery, discounts, product launches, seasonal campaigns. Requires recipient opt-in consent and respects Meta sending limits.
Request Body Parameters
| Field | Type | Description |
|---|---|---|
| to | string (required) | Recipient mobile number in standard E.164 format with country code (e.g. +919876543210 or 919876543210). Non-digit characters like spaces and hyphens are automatically sanitized by the gateway. |
| template_name | string (required) | The exact identifier slug of your approved Meta WhatsApp template (e.g. order_confirmation_v2, auth_otp_code). Must match case-sensitively. |
| language | string (optional) | Language code of the template (defaults to en). Supports hi (Hindi), en_US, gu, mr, ta, te, bn, etc. |
| variables | object | array (optional) | Key-value map or indexed array of body variables. Both named tags ({"customer_name": "Rahul"}) and numeric indexes ({"1": "Rahul", "2": "ORD-991"}) are fully supported and mapped automatically. |
| button_variables | array of strings (optional) | Dynamic parameters for call-to-action buttons. For OTP templates, pass the OTP string (e.g. ["489201"]) to populate the one-tap "Copy Code" button. For dynamic URL buttons, pass the suffix/tracking parameter. |
| header_type | string (optional) | Specifies media header format when template uses dynamic media. Values: image, document, or video. |
| header_url | string URL (optional) | Public HTTPS link for media headers. Supports images (JPG/PNG/WebP up to 5MB), documents (PDF invoices up to 100MB), and videos (MP4 up to 16MB). |
| header_filename | string (optional) | Custom file display name for PDF documents (e.g. Tax-Invoice-88219.pdf). |
Interactive Code Examples
curl -X POST https://api.softymize.com/api/v1/whatsapp/send \ -H "X-Softymize-API-Key: sft_live_9b8a7c6d5e4f3a2b1" \ -H "X-Idempotency-Key: ord_confirm_99182a" \ -H "Content-Type: application/json" \ -d '{ "to": "+919876543210", "template_name": "order_confirmation_v2", "language": "en", "variables": { "customer_name": "Rahul Sharma", "order_id": "ORD-88219", "amount": "₹2,499.00", "delivery_date": "Tomorrow, by 7 PM" }, "header_type": "document", "header_url": "https://cdn.mybrand.com/receipts/inv-88219.pdf", "header_filename": "Tax-Invoice-88219.pdf", "button_variables": ["ORD-88219"] }'Response Envelope Schemas
{ "success": true, "message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSMzNFODQzMTk4NDY5Mjc4RDkyAA==", "channel": "whatsapp", "template_name": "order_confirmation_v2", "status": "dispatched", "recipient": "+919876543210", "meta": { "workspace_id": "ws_9a8b7c6d5e", "queue_latency_ms": 4, "tier": "tier_3_100k", "timestamp": "2026-10-17T18:50:00Z" }}{ "success": false, "error": { "code": "VARIABLE_COUNT_MISMATCH", "message": "Template 'order_confirmation_v2' expects 4 body variables [customer_name, order_id, amount, delivery_date], but only 3 were supplied.", "doc_url": "https://docs.softymize.com/api-docs/whatsapp#error-dictionary" }, "meta": { "request_id": "req_8a1b2c3d4e5f6g7h", "timestamp": "2026-10-17T18:50:01Z" }}Error Dictionary & Troubleshooting Guide
The table below explains all potential error codes returned by the WhatsApp gateway and the exact resolution steps:
| Error Code | HTTP Status | Cause | Resolution |
|---|---|---|---|
| TEMPLATE_NOT_APPROVED | 422 | The specified template_name is in "PENDING" or "REJECTED" status in Meta Business Manager. | Ensure the template shows "APPROVED" (Green) in your Softymize dashboard or Meta WhatsApp Manager before dispatching. |
| VARIABLE_COUNT_MISMATCH | 422 | The approved template has 4 placeholder tags, but fewer or more were provided in variables. | Verify the exact parameter count in template details and supply all required keys. |
| PHONE_NOT_ON_WHATSAPP | 422 | The recipient mobile number is invalid or has no active WhatsApp account. | Validate number format via OTP or phone verification during user checkout. |
| RATE_LIMIT_EXCEEDED | 429 | Dispatched more than 50 API requests per second or exceeded 24h phone number tier limit. | Implement exponential backoff. Contact Softymize Support to upgrade your workspace sending tier. |
| MEDIA_DOWNLOAD_FAILED | 422 | Meta's media crawler failed to download header_url within 10 seconds. | Ensure the image or PDF URL is publicly reachable over HTTPS without IP restrictions or CAPTCHA. |
Real-Time Delivery & Read Receipt Webhooks
Softymize automatically dispatches outgoing webhooks to your server when the customer receives or opens the message. Configure your endpoint in Workspace > Settings > Webhooks:
{ "event": "message.sent", "message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSMzNFODQzMTk4NDY5Mjc4RDkyAA==", "recipient": "+919876543210", "status": "sent", "channel": "whatsapp", "timestamp": 1729188600}{ "event": "message.delivered", "message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSMzNFODQzMTk4NDY5Mjc4RDkyAA==", "recipient": "+919876543210", "status": "delivered", "channel": "whatsapp", "delivered_at": "2026-10-17T18:50:02Z", "timestamp": 1729188602}{ "event": "message.read", "message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSMzNFODQzMTk4NDY5Mjc4RDkyAA==", "recipient": "+919876543210", "status": "read", "channel": "whatsapp", "read_at": "2026-10-17T18:50:15Z", "timestamp": 1729188615}Best Practices for 99.9% Delivery & High Meta Quality Rating
- Explicit Opt-in: Collect consent on checkout (e.g. checkbox: "Send order tracking updates on WhatsApp") to prevent user blocks and spam reports.
- Phone Number Warming: For brand new WhatsApp phone numbers, start with 200-500 high-intent transactional messages per day before launching large marketing broadcasts.
- Monitor Meta Phone Quality: Keep your rating High (Green) inside Softymize Dashboard. If ratings drop to Medium (Yellow), pause promotional campaigns and review opt-out options.
- Idempotency Keys: Always transmit
X-Idempotency-Keyfor payment transactions and OTP verifications to guarantee zero duplicate charges or confusion.