Saltar al contenido principal

WhatsApp Template Setup Guide for Twilio

📱 WhatsApp Business Messaging Restrictions​

WhatsApp has strict policies for business messaging to prevent spam and protect users:

24-Hour Messaging Window​

  • You can only send freeform messages within a 24-hour window after a customer last messaged you
  • Outside this window, you MUST use pre-approved Message Templates
  • This applies to:
    • ❌ First-time messages to customers (invoices, notifications, etc.)
    • ❌ Messages after 24 hours of customer silence
    • ✅ Replies within 24 hours of customer message

Error Code 63016​

If you see this error: Failed to send freeform message because you are outside the allowed window, it means you need to use a Message Template.

🚀 Setting Up WhatsApp Message Templates​

Step 1: Access Twilio Content Templates​

  1. Log in to Twilio Console
  2. Navigate to: Messaging → Content Templates → Content Template Builder
  3. Click Create new Template

Step 2: Choose Template Type​

  • WhatsApp (Select this)
  • Template Language: Choose your language (e.g., English, Spanish)

Step 3: Create Your Template​

Template Structure:​

Templates consist of:

  1. Template Name: Internal identifier (e.g., invoice_whatsapp)
  2. Category: Purpose of message
    • TRANSACTIONAL: Invoices, orders, confirmations
    • MARKETING: Promotions, offers
    • UTILITY: Account updates, reminders
  3. Header (Optional): Image, document, or text
  4. Body: Main message content with variables
  5. Footer (Optional): Additional info
  6. Buttons (Optional): Call-to-action buttons

📝 Template Examples for FlowPOS​

1. Invoice Template​

Template Name: invoice_whatsapp
Category: TRANSACTIONAL
Language: English

Body:

Hello {{1}},

Your invoice #{{2}} has been generated.

Amount due: {{3}}
Due date: {{4}}

Thank you for your business!

Variables:

  1. {{1}} = Customer Name
  2. {{2}} = Invoice Number
  3. {{3}} = Amount (formatted)
  4. {{4}} = Due Date

2. Payment Reminder Template​

Template Name: payment_reminder_whatsapp
Category: TRANSACTIONAL
Language: English

Body:

Hi {{1}},

This is a reminder that invoice #{{2}} for {{3}} is due on {{4}}.

Please make payment at your earliest convenience.

Thank you!

Variables:

  1. {{1}} = Customer Name
  2. {{2}} = Invoice Number
  3. {{3}} = Amount
  4. {{4}} = Due Date

3. Order Confirmation Template​

Template Name: order_confirmation_whatsapp
Category: TRANSACTIONAL
Language: English

Body:

Hi {{1}},

Your order #{{2}} has been confirmed!

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

Thank you for shopping with {{5}}!

Variables:

  1. {{1}} = Customer Name
  2. {{2}} = Order Number
  3. {{3}} = Total Amount
  4. {{4}} = Delivery Date
  5. {{5}} = Business Name

4. Low Stock Alert Template​

Template Name: low_stock_alert_whatsapp
Category: UTILITY
Language: English

Body:

⚠️ Low Stock Alert

Product: {{1}}
Current stock: {{2}} units
Reorder level: {{3}} units

Please reorder soon to avoid stockouts.

Variables:

  1. {{1}} = Product Name
  2. {{2}} = Current Stock
  3. {{3}} = Reorder Level

✅ Step 4: Submit for Approval​

  1. Review your template
  2. Click Submit for Approval
  3. Approval Time: Usually 1-24 hours (sometimes instant)
  4. You'll receive an email when approved/rejected

📋 Step 5: Get Template SID​

Once approved:

  1. Go to Messaging → Content Templates
  2. Find your template
  3. Click on it
  4. Copy the Content SID (format: HXe835f49d0aa7f1639f7f8e4b8a1e6c1e)

🔧 Step 6: Update FlowPOS Database​

Update the template in FlowPOS:

curl --location --request PATCH 'https://your-api-url.com/communication-templates/{template-id}' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "providerTemplateId": "HXe835f49d0aa7f1639f7f8e4b8a1e6c1e"
}'

Option B: Direct Database Update​

UPDATE communication_template
SET provider_template_id = 'HXe835f49d0aa7f1639f7f8e4b8a1e6c1e'
WHERE code = 'invoice_whatsapp'
AND channel = 'whatsapp';

🚀 Step 7: Send WhatsApp Message with Template​

Using the API​

curl --location --request POST 'https://your-api-url.com/communications/send' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "businessId": "your-business-id",
    "createdBy": "your-user-id",
    "channel": "whatsapp",
    "type": "invoice",
    "recipientType": "customer",
    "recipientId": "customer-id",
    "recipientContact": "+50256917111",
    "templateId": "template-id-from-flowpos",
    "templateVariables": {
        "1": "John Doe",
        "2": "INV-001",
        "3": "$150.00",
        "4": "2025-11-01"
    },
    "priority": "normal"
}'

Important Notes:

  • Variables are numbered: "1", "2", "3", etc. (not "{{1}}")
  • Variables must be strings
  • The system automatically uses the providerTemplateId from the template

🎯 Best Practices​

1. Template Naming Convention​

  • Use descriptive names: invoice_whatsapp, payment_reminder_whatsapp
  • Include channel in name for clarity
  • Keep it consistent across your system

2. Variable Management​

  • Use numbered variables {{1}}, {{2}}, etc.
  • Keep variable count reasonable (max 10-15)
  • Document what each variable represents

3. Content Guidelines​

  • Keep messages concise and clear
  • Include business name for brand recognition
  • Use emojis sparingly (✅ ❌ ⚠️ are good)
  • Avoid spammy language

4. Testing​

  • Test templates with your own phone number first
  • Verify all variables render correctly
  • Check character limits (WhatsApp max: 4096 chars)

5. Fallback Strategy​

  • Have SMS templates as fallback
  • Monitor delivery rates
  • Handle template rejection gracefully

🔍 Troubleshooting​

Template Rejected​

Common Reasons:

  • ❌ Contains promotional language in TRANSACTIONAL category
  • ❌ Unclear purpose or business use case
  • ❌ Grammar or spelling errors
  • ❌ Misleading content

Solution: Review WhatsApp's Template Guidelines

Error 63016: Outside 24-Hour Window​

Solution: You're using freeform messages instead of templates. Use the template system described above.

Template Variables Not Working​

Check:

  • Variables are numbered correctly (1, 2, 3, not {{1}})
  • All required variables are provided
  • Variables are strings, not numbers or objects

Template Not Found​

Check:

  • Template is approved by Meta/WhatsApp
  • Correct Content SID is stored in provider_template_id
  • Template is active in FlowPOS database

📊 Monitoring​

Track Template Performance​

  1. Twilio Console:

    • Go to Messaging → Insights
    • View delivery rates, open rates

  2. FlowPOS Dashboard:

    • Check communication table
    • Monitor status field
    • Track deliveredAt, failedAt timestamps

🔐 Security Notes​

  • Never hardcode Content SIDs in code
  • Store SIDs in database (provider_template_id field)
  • Use environment variables for Twilio credentials
  • Implement rate limiting to avoid hitting Twilio limits

📚 Additional Resources​

💡 Next Steps​

  1. ✅ Create your first template
  2. ✅ Wait for approval
  3. ✅ Update FlowPOS database with Content SID
  4. ✅ Test sending a message
  5. ✅ Monitor delivery and adjust as needed

🎉 Success​

You're now ready to send WhatsApp messages at scale without hitting the 24-hour window restriction!

For questions or issues, refer to the troubleshooting section or contact support.