Skip to main content

​
WhatsApp Business API

Mindhunters integrates with WhatsApp Business API to enable automated messaging at scale. Send notifications, confirmations, and updates directly to your customers’ WhatsApp.

​
Prerequisites

Before you can send WhatsApp messages, you need:
1

WhatsApp Business Account

Set up a WhatsApp Business account through Meta
2

Message Templates

Create and get approval for message templates
3

Connect to Mindhunters

Link your WhatsApp Business account in Mindhunters dashboard

​
Message Templates

WhatsApp requires pre-approved templates for outbound messages. Templates ensure compliance with WhatsApp policies and prevent spam.

​
Template Structure

A template consists of:
  • Template Name: Unique identifier
  • Language: Message language code
  • Category: Marketing, Utility, or Authentication
  • Content: Header, body, footer, and buttons
  • Parameters: Dynamic placeholders for personalization

​
Template Example

Template Name: appointment_reminder
Category: Utility
Language: en

Header: Your Appointment Reminder
Body: Hi {{1}}, this is a reminder for your appointment on {{2}} at {{3}}. Reply CONFIRM to confirm or CANCEL to reschedule.
Footer: Powered by Acme Corp
Buttons: [Quick Reply: CONFIRM] [Quick Reply: CANCEL]

​
Creating Templates

  • Via Dashboard
  • Via Meta Business Manager
  1. Log in to Mindhunters dashboard
  2. Go to WhatsApp → Templates
  3. Click “Create Template”
  4. Fill in template details
  5. Submit for WhatsApp approval
  6. Wait for approval (usually 24-48 hours)

​
Template Categories

CategoryPurposeExample Use Cases
MarketingPromotional messagesSales, offers, newsletters
UtilityTransaction updatesOrder confirmations, shipping updates, reminders
AuthenticationVerification codesOTP, password resets, login codes
Marketing templates have more restrictions and may have lower delivery rates. Use Utility or Authentication categories when possible.

​
Sending Messages via API

Once your templates are approved, you can send messages programmatically.

​
Basic Example

curl -X POST https://your-tenant.mindhunters.ai/api/v1/whatsapp/template \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent-uuid-here",
    "templateId": "template-uuid-here",
    "participant": {
      "number": "+1234567890",
      "name": "John Doe"
    },
    "parameters": ["John", "March 15", "2:00 PM"]
  }'

​
With Media

Send templates with images or documents: 
{
  "agentId": "agent-uuid-here",
  "templateId": "template-uuid-here",
  "participant": {
    "number": "+1234567890"
  },
  "parameters": ["John Doe", "ORD-12345"],
  "media": {
    "type": "image",
    "url": "https://example.com/invoice.jpg"
  }
}

​
Use Cases

​
Order Confirmations

Template
Name: order_confirmation
Category: Utility

Hi {{1}}! Your order #{{2}} has been confirmed.

Total: ${{3}}
Expected delivery: {{4}}

Track your order: {{5}}

Thank you for shopping with us!

​
Appointment Reminders

Template
Name: appointment_reminder
Category: Utility

Hello {{1}},

Reminder: You have an appointment on {{2}} at {{3}}.

Location: {{4}}

Reply CONFIRM to confirm or CANCEL to reschedule.

​
Shipping Updates

Template
Name: shipping_update
Category: Utility

Great news {{1}}! Your order #{{2}} has shipped.

Tracking: {{3}}
Estimated delivery: {{4}}

Track shipment: {{5}}

​
Payment Reminders

Template
Name: payment_reminder
Category: Utility

Hi {{1}},

Your payment of ${{2}} is due on {{3}}.

Pay now: {{4}}

Questions? Reply to this message.

​
Best Practices

  • Submit templates for approval before you need them
  • Allow 24-48 hours for approval
  • Have backup templates ready
  • Keep rejected templates for reference
  • Use customer names
  • Include relevant order/account details
  • Make messages specific to the recipient
  • Avoid generic broadcasts
  • Honor customer preferences
  • Provide easy opt-out options
  • Don’t message opted-out contacts
  • Keep unsubscribe list updated
  • Send messages during business hours
  • Consider recipient’s timezone
  • Don’t send too frequently
  • Space out campaigns appropriately
  • Track delivery and read rates
  • Monitor for failed deliveries
  • Check template performance
  • Optimize based on metrics

​
Template Approval Tips

To get templates approved faster: ✅ Do:
  • Be clear and concise
  • Use proper grammar and spelling
  • Include opt-out instructions for marketing
  • Follow WhatsApp policies
  • Provide value to recipients
❌ Don’t:
  • Use all caps
  • Include misleading content
  • Make false claims
  • Use excessive emojis
  • Violate WhatsApp policies

​
Handling Responses

​
Receiving Replies

When customers reply to your messages, you can handle them via webhooks:
Webhook Example
{
  "event": "whatsapp.message.received",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "from": "+1234567890",
    "message": "CONFIRM",
    "conversationId": "conv-uuid",
    "templateId": "template-uuid"
  }
}
Set up webhooks to receive and process customer responses. See the Webhooks Guide for details.

​
Compliance

​
WhatsApp Policies

  • 24-hour Window: After customer initiates, you have 24 hours to send free-form messages
  • Templates Required: Outside 24-hour window, use approved templates
  • Opt-in Required: Customers must opt-in to receive messages
  • Quality Rating: Maintain high quality rating to avoid limits

​
Data Privacy

  • Comply with GDPR and local privacy laws
  • Get explicit consent before messaging
  • Provide clear opt-out mechanisms
  • Protect customer data
  • Don’t share data with third parties

​
Troubleshooting

​
Template Rejected

Common reasons:
  • Policy violation
  • Grammatical errors
  • Misleading content
  • Missing required elements
  • Inappropriate content
Solution: Review WhatsApp guidelines, revise template, resubmit.

​
Message Not Delivered

Possible causes:
  • Invalid phone number
  • User blocked business
  • Template not approved
  • Rate limits exceeded
  • Opt-out list
Solution: Check logs, verify number format, review opt-out status.

​
Parameters Not Replacing

Possible causes:
  • Wrong parameter order
  • Incorrect parameter count
  • Type mismatch
Solution: Ensure parameter array matches template placeholders exactly.

​
Monitoring & Analytics

Track WhatsApp message performance:

​
Available Metrics

  • Sent: Total messages sent
  • Delivered: Successfully delivered
  • Read: Messages read by recipient
  • Failed: Delivery failures
  • Response Rate: Percentage of replies

​
Viewing Stats

  1. Go to WhatsApp → Analytics
  2. Select date range
  3. Filter by template
  4. Export data as needed

​
Rate Limits

WhatsApp has quality-based rate limits:
Quality RatingDaily Message Limit
High100,000 messages
Medium10,000 messages
Low1,000 messages
Maintain high quality by:
  • Sending relevant messages
  • Honoring opt-outs
  • Using approved templates
  • Avoiding spam reports

​
Next Steps

API Reference

View complete WhatsApp API docs

Webhooks

Handle incoming messages

Campaigns

Create WhatsApp campaigns

Monitoring

Track message performance