Skip to main content

​
Overview

Send WhatsApp messages to your contacts using pre-approved templates. Perfect for:
  • Transactional notifications: Order updates, booking confirmations
  • Customer support: Appointment reminders, service updates
  • Marketing messages: Product launches, promotional offers (with opt-in)
  • Authentication: OTP codes, verification messages
Before sending messages, make sure to connect a WhatsApp Business Account by visiting the Channels section at app.minimo.it/channels.

​
WhatsApp Template Requirements

Unlike emails, WhatsApp messages must use templates approved by Meta (Facebook). This ensures:
  • User privacy and experience
  • Compliance with WhatsApp Business Policy
  • Reduced spam and unwanted messages

​
Template Approval Process

  1. Create template in Minimo dashboard
  2. Submit for approval to Meta
  3. Wait 24-48 hours for review
  4. Use approved template via API
Only templates with status: "APPROVED" can be used. Attempting to send with pending or rejected templates will fail.

​
Template Categories

WhatsApp templates must be categorized:
CategoryDescriptionUse Cases24h Window
UTILITYAccount updates, transactionsOrder status, booking confirmationNo
AUTHENTICATIONOTP codes, verification2FA codes, login verificationNo
MARKETINGPromotional contentProduct launch, special offersYes*
*Marketing templates require user opt-in and are subject to the 24-hour messaging window.

​
Phone Number Format

WhatsApp requires phone numbers in E.164 format: 
+[country code][subscriber number]
Examples:
  • ✅ +393391234567 (Italy)
  • ✅ +12025551234 (US)
  • ✅ +447700900123 (UK)
  • ❌ 3391234567 (missing country code)
  • ❌ +39 339 123 4567 (contains spaces)
  • ❌ +39-339-123-4567 (contains dashes)
Always validate and format phone numbers before sending. Invalid numbers will result in failed messages and count against your quality score.

​
Template Variables

Templates support dynamic content with numbered placeholders: Template Example (created in dashboard): 
Hello {{1}}, your order {{2}} has been confirmed!

Total: {{3}}
Estimated delivery: {{4}}

Track your order: {{5}}
API Request: 
{
  "templateName": "order_confirmation",
  "phone": "+393391234567",
  "components": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "Jane Doe" },
        { "type": "text", "text": "ORD-12345" },
        { "type": "text", "text": "$99.99" },
        { "type": "text", "text": "November 20, 2025" },
        { "type": "text", "text": "https://track.example.com/12345" }
      ]
    }
  ]
}
Variable numbering starts at {{1}}, not {{0}}. Order matters - map parameters in the exact sequence defined in your template.

​
WhatsApp Message Components

Templates can have multiple components:

​
Header (Optional)

  • Text, image, document, or video
  • Single dynamic variable supported

​
Body (Required)

  • Main message content
  • Supports multiple variables
  • Maximum 1024 characters
  • Additional info (e.g., “Reply STOP to opt-out”)
  • No variables allowed

​
Buttons (Optional)

  • Call-to-action buttons
  • Quick reply buttons
  • URL buttons with dynamic parameters

​
Use Cases

Send instant confirmation when an order is placed:
{
  "templateName": "order_confirmation",
  "phone": "+393391234567",
  "components": [
    {
      "type": "body",
      "parameters": [
        {"type": "text", "text": "Mario Rossi"},
        {"type": "text", "text": "ORD-789"},
        {"type": "text", "text": "€149.99"}
      ]
    }
  ]
}
Remind customers about upcoming appointments:
{
  "templateName": "appointment_reminder",
  "phone": "+393391234567",
  "components": [
    {
      "type": "body",
      "parameters": [
        {"type": "text", "text": "Dr. Smith"},
        {"type": "text", "text": "November 15, 2025"},
        {"type": "text", "text": "10:30 AM"},
        {"type": "text", "text": "Via Roma 123, Milano"}
      ]
    }
  ]
}
Send one-time passwords securely:
{
  "templateName": "otp_code",
  "phone": "+393391234567",
  "components": [
    {
      "type": "body",
      "parameters": [
        {"type": "text", "text": "847592"},
        {"type": "text", "text": "5 minutes"}
      ]
    }
  ]
}
Notify customers about delivery status:
{
  "templateName": "shipping_update",
  "phone": "+393391234567",
  "components": [
    {
      "type": "body",
      "parameters": [
        {"type": "text", "text": "ORD-12345"},
        {"type": "text", "text": "Out for delivery"},
        {"type": "text", "text": "https://track.example.com/12345"}
      ]
    }
  ]
}

​
Best Practices

​
Message Quality Score

WhatsApp monitors your message quality. Maintain a high quality score by:
  • ✅ Only sending to users who opted in
  • ✅ Sending relevant, timely messages
  • ✅ Using clear, professional language
  • ✅ Respecting the 24-hour window for marketing
  • ❌ Avoid spam-like behavior
  • ❌ Don’t send unsolicited messages
  • ❌ Don’t exceed rate limits
Poor quality scores can result in: - Reduced sending limits - Template rejections - Account suspension

​
Phone Number Validation

Always validate before sending: 
function isValidE164(phone) {
  // Basic E.164 validation
  return /^\+[1-9]\d{1,14}$/.test(phone);
}

if (!isValidE164(phone)) {
  console.error('Invalid phone number format');
  return;
}

​
Template Design Guidelines

  • Be concise: Keep messages short and clear
  • Add context: Include order numbers, dates, etc.
  • Include branding: Mention your company name
  • Provide value: Every message should be useful
  • Call-to-action: Make next steps obvious

​
Rate Limits & Messaging Tiers

WhatsApp enforces tiered messaging limits:
TierDaily LimitHow to Advance
Tier 11,000Maintain quality score
Tier 210,000Consistent quality + volume
Tier 3100,000High quality + high volume
Tier 4UnlimitedEnterprise approval
Start at Tier 1, advance automatically with good performance.

​
Common Errors

ErrorCauseSolution
template_not_approvedTemplate pending/rejectedCheck status in dashboard, resubmit if needed
invalid_phone_numberPhone not in E.164 formatAdd country code, remove spaces/dashes
template_not_foundWrong template nameVerify template name in dashboard
parameter_mismatchWrong number of variablesMatch template variable count exactly
rate_limit_exceededMessaging tier limit reachedWait for reset or request tier upgrade
recipient_not_on_whatsappPhone number not on WhatsAppVerify number is active on WhatsApp

​
Tracking & Analytics

Monitor message delivery and engagement:
  • Delivery status: Sent, delivered, read
  • Failure reasons: Why messages didn’t deliver
  • Response rate: How many users reply
Access analytics via the Get WhatsApp Template Stats endpoint or Minimo dashboard.

​
24-Hour Messaging Window

​
For Marketing Templates

After a user-initiated conversation, you have a 24-hour window to send marketing messages without requiring a new opt-in. User-initiated means:
  • User sends a message to your WhatsApp number
  • User clicks a WhatsApp link
  • User interacts with your WhatsApp ad
Outside the 24-hour window: Only UTILITY and AUTHENTICATION templates can be sent.
UTILITY templates (order confirmations, booking updates) can be sent anytime, regardless of the 24-hour window.

​
Compliance & Opt-In

  • Get explicit opt-in before sending WhatsApp messages
  • Keep records of consent
  • Honor opt-out requests immediately
  • Follow GDPR and local privacy regulations

​
Opt-Out Handling

Include opt-out instructions in templates: 
Don't want to receive these messages? Reply STOP to opt out.