Send WhatsApp API

Send WhatsApp messages to specific recipients, contacts, tags, or all contacts. Uses Meta-approved templates with variable substitution and supports scheduling.

Endpoint

POST /api/v1/whatsapp/send

Headers

X-API-Key: sk_live_your_api_key
Content-Type: application/json

Quick Example

curl -X POST https://api.sendmator.com/api/v1/whatsapp/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "order_confirmation",
    "recipient_type": "direct_whatsapp",
    "direct_whatsapp": "+1234567890",
    "conversation_category": "UTILITY",
    "variables": {
      "order_id": "12345",
      "delivery_date": "March 20"
    }
  }'

Request Parameters

Required Fields

Field	Type	Description
`template_key`	string	WhatsApp template identifier (must be Meta-approved)
`recipient_type`	string	How to target recipients: `direct_whatsapp`, `contact`, `tag`, `all`
`conversation_category`	string	WhatsApp conversation category: `MARKETING`, `UTILITY`, `AUTHENTICATION`

Recipient-Specific Fields

Recipient Type	Required Field	Type	Description
`direct_whatsapp`	`direct_whatsapp`	string	Phone number in E.164 format (e.g., `+1234567890`)
`contact`	`contact_external_id`	string	External ID of the contact
`tag`	`tag`	string[]	Array of tags to match
`all`	(none)	-	Sends to all active contacts with WhatsApp opt-in

Optional Fields for Direct WhatsApp

Field	Type	Description
`direct_first_name`	string	Recipient's first name (for personalization)
`direct_last_name`	string	Recipient's last name (for personalization)

Common Optional Fields

Field	Type	Description
`variables`	object	Template variables (key-value pairs)
`metadata`	object	Custom tracking data
`triggerAt`	string	ISO 8601 UTC timestamp for scheduled send
`whatsapp_identity_id`	string	WhatsApp identity UUID (defaults to user's default)
`campaign_name`	string	Campaign name for tracking purposes

Conversation Categories

WhatsApp requires you to specify the conversation category for billing and compliance:

Category	Description	Use Cases	Example
MARKETING	Promotional messages	Sales, offers, updates	"50% off this weekend!"
UTILITY	Account updates, transactions	Order confirmations, shipping updates	"Your order has shipped"
AUTHENTICATION	OTPs, verification codes	Login codes, 2FA	"Your verification code is 123456"

Complete Examples

1. Send Direct WhatsApp OTP

Send to a specific phone number for authentication:

curl -X POST https://api.sendmator.com/api/v1/whatsapp/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "otp_verification",
    "recipient_type": "direct_whatsapp",
    "direct_whatsapp": "+1234567890",
    "direct_first_name": "John",
    "conversation_category": "AUTHENTICATION",
    "variables": {
      "otp_code": "123456",
      "expiry_minutes": "10"
    }
  }'

Response:

{
  "success": true,
  "trigger_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_id": "123",
  "message": "WhatsApp message queued successfully"
}

Use Cases:

OTP verification
2FA authentication
Account verification
Password reset codes

2. Send Order Confirmation to Contact

Send to a specific contact using their external ID:

curl -X POST https://api.sendmator.com/api/v1/whatsapp/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "order_confirmation",
    "recipient_type": "contact",
    "contact_external_id": "user-123",
    "conversation_category": "UTILITY",
    "variables": {
      "order_id": "ORD-12345",
      "total_amount": "$99.99",
      "delivery_date": "March 20, 2026"
    }
  }'

Response:

{
  "success": true,
  "trigger_id": "abc123-def456-ghi789",
  "job_id": "124",
  "message": "WhatsApp message queued successfully"
}

Use Cases:

Order confirmations
Shipping updates
Appointment reminders
Account notifications

Auto-populated Variables: When sending to a contact, their data is automatically available:

{{contact_first_name}} - Contact's first name
{{contact_last_name}} - Contact's last name
{{contact_phone}} - Contact's WhatsApp number
{{contact_external_id}} - Contact's external ID

3. Send Promotional Message to Tagged Contacts

Send marketing messages to specific customer segments:

curl -X POST https://api.sendmator.com/api/v1/whatsapp/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "flash_sale",
    "recipient_type": "tag",
    "tag": ["premium", "vip"],
    "conversation_category": "MARKETING",
    "campaign_name": "Spring Sale 2026",
    "variables": {
      "discount_percentage": "40",
      "sale_end_date": "March 31"
    }
  }'

Response:

{
  "success": true,
  "trigger_id": "pqr901-stu234-vwx567",
  "job_id": "125",
  "message": "WhatsApp message queued successfully"
}

Use Cases:

Flash sales
Product launches
Event invitations
VIP promotions

4. Scheduled WhatsApp Message

Schedule a WhatsApp message for future delivery:

curl -X POST https://api.sendmator.com/api/v1/whatsapp/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "appointment_reminder",
    "recipient_type": "contact",
    "contact_external_id": "user-123",
    "conversation_category": "UTILITY",
    "variables": {
      "appointment_date": "March 20, 2026",
      "appointment_time": "2:00 PM",
      "doctor_name": "Dr. Smith"
    },
    "triggerAt": "2026-03-19T14:00:00Z"
  }'

Response:

{
  "success": true,
  "trigger_id": "lmn012-opq345-rst678",
  "job_id": "126",
  "message": "WhatsApp message scheduled successfully",
  "scheduled_for": "2026-03-19T14:00:00Z",
  "delay_ms": 86400000
}

Use Cases:

Appointment reminders
Event notifications
Scheduled announcements
Time-zone specific sends

Response Format

Success Response (201 Created)

{
  "success": true,
  "trigger_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_id": "123",
  "message": "WhatsApp message queued successfully"
}

Field	Type	Description
`success`	boolean	Always `true` for successful requests
`trigger_id`	string	Unique ID to track this send operation
`job_id`	string	Job queue ID for monitoring
`message`	string	Human-readable status message

Error Responses

Template Not Approved (400)

{
  "statusCode": 400,
  "message": "WhatsApp template 'order_confirmation' is not approved by Meta",
  "error": "Bad Request"
}

Invalid Conversation Category (400)

{
  "statusCode": 400,
  "message": "conversation_category must be one of: MARKETING, UTILITY, AUTHENTICATION",
  "error": "Bad Request"
}

Contact Not Found (404)

{
  "statusCode": 404,
  "message": "Contact with external_id 'user-123' not found",
  "error": "Not Found"
}

Insufficient Balance (400)

{
  "statusCode": 400,
  "message": "Insufficient wallet balance. Required: 15.00 USD, Available: 5.00 USD. Please recharge your wallet to continue.",
  "error": "Bad Request"
}

WhatsApp Templates

All WhatsApp messages must use Meta-approved templates. You cannot send free-form text messages.

Template Requirements

Meta Approval: All templates must be submitted to and approved by Meta
Template Structure: Fixed structure with variable placeholders
Language: Templates must be created for each language
Categories: Must match the conversation category (MARKETING, UTILITY, AUTHENTICATION)

Template Variables

Use placeholders in your templates:

Hello {{1}}, your order {{2}} has been confirmed. Delivery by {{3}}.

Then pass variables in order:

{
  "variables": {
    "1": "John",
    "2": "#12345",
    "3": "March 20"
  }
}

Media Support

WhatsApp templates can include:

Images: Header images for rich messaging
Videos: Product demos or announcements
Documents: PDFs, receipts, invoices
Buttons: Call-to-action buttons (URL, Quick Reply, Phone Number)

24-Hour Window Rule

WhatsApp enforces a 24-hour messaging window:

Within 24 hours: You can send any approved template
After 24 hours: Only template messages (with conversation category charges)
User-initiated: Clock resets when user sends a message to you

Best Practice: Use utility templates for follow-ups within the 24-hour window to avoid marketing conversation charges.

Pricing

WhatsApp pricing varies by conversation category and region:

Category	Region	Approximate Price
Authentication	USA	~$0.005/conversation
Utility	USA	~$0.01/conversation
Marketing	USA	~$0.03/conversation
Authentication	India	~$0.0025/conversation
Utility	India	~$0.004/conversation
Marketing	India	~$0.01/conversation

Note:

Conversations are 24-hour windows, not per-message
Multiple messages within 24 hours = 1 conversation charge
Different categories = different conversations

Best Practices

1. Choose the Right Category

# ✅ Good: Authentication for OTPs
{
  "conversation_category": "AUTHENTICATION",
  "template_key": "otp_verification"
}

# ✅ Good: Utility for transactional updates
{
  "conversation_category": "UTILITY",
  "template_key": "order_shipped"
}

# ⚠️ Marketing costs more - use sparingly
{
  "conversation_category": "MARKETING",
  "template_key": "promotional_offer"
}

2. Get Templates Pre-Approved

Before going live:

Create templates in Sendmator dashboard
Submit to Meta for review
Wait for approval (usually 24-48 hours)
Test with approved templates only

3. Respect Opt-In Requirements

MARKETING category requires explicit opt-in:

User must have opted in to marketing messages
Sendmator automatically filters non-opted-in contacts
UTILITY and AUTHENTICATION have more lenient rules

4. Use Variables Effectively

# ✅ Good: Clear variable names in order
{
  "variables": {
    "1": "John",
    "2": "#12345",
    "3": "March 20"
  }
}

# ❌ Avoid: Out of order or missing variables
{
  "variables": {
    "3": "March 20",
    "1": "John"
    // Missing variable 2!
  }
}

5. Test Before Broadcasting

# Step 1: Test with yourself
{
  "recipient_type": "direct_whatsapp",
  "direct_whatsapp": "+your-number"
}

# Step 2: Test with small group
{
  "recipient_type": "tag",
  "tag": ["internal-team"]
}

# Step 3: Send to everyone
{
  "recipient_type": "all"
}

Multi-Channel Messages

To send messages across multiple channels (Email, SMS, WhatsApp, Push) simultaneously, use the Multi-Channel Trigger API instead of /whatsapp/send.

Next Steps

Create WhatsApp Templates - Get templates approved by Meta
Manage Contacts - Build your contact database
Multi-Channel API - Send across multiple channels
API Overview - Explore other endpoints

Endpoint​

Headers​

Quick Example​

Request Parameters​

Required Fields​

Recipient-Specific Fields​

Optional Fields for Direct WhatsApp​

Common Optional Fields​

Conversation Categories​

Complete Examples​

1. Send Direct WhatsApp OTP​

2. Send Order Confirmation to Contact​

3. Send Promotional Message to Tagged Contacts​

4. Scheduled WhatsApp Message​

Response Format​

Success Response (201 Created)​

Error Responses​

Template Not Approved (400)​

Invalid Conversation Category (400)​

Contact Not Found (404)​

Insufficient Balance (400)​

WhatsApp Templates​

Template Requirements​

Template Variables​

Media Support​

24-Hour Window Rule​

Pricing​

Best Practices​

1. Choose the Right Category​

2. Get Templates Pre-Approved​

3. Respect Opt-In Requirements​

4. Use Variables Effectively​

5. Test Before Broadcasting​

Multi-Channel Messages​

Next Steps​

Endpoint

Headers

Quick Example

Request Parameters

Required Fields

Recipient-Specific Fields

Optional Fields for Direct WhatsApp

Common Optional Fields

Conversation Categories

Complete Examples

1. Send Direct WhatsApp OTP

2. Send Order Confirmation to Contact

3. Send Promotional Message to Tagged Contacts

4. Scheduled WhatsApp Message

Response Format

Success Response (201 Created)

Error Responses

Template Not Approved (400)

Invalid Conversation Category (400)

Contact Not Found (404)

Insufficient Balance (400)

WhatsApp Templates

Template Requirements

Template Variables

Media Support

24-Hour Window Rule

Pricing

Best Practices

1. Choose the Right Category

2. Get Templates Pre-Approved

3. Respect Opt-In Requirements

4. Use Variables Effectively

5. Test Before Broadcasting

Multi-Channel Messages

Next Steps