> ## Documentation Index
> Fetch the complete documentation index at: https://developers.mindhunters.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Messaging

> Send automated WhatsApp messages using pre-approved templates

## 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:

<Steps>
  <Step title="WhatsApp Business Account">
    Set up a WhatsApp Business account through Meta
  </Step>

  <Step title="Message Templates">
    Create and get approval for message templates
  </Step>

  <Step title="Connect to Mindhunters">
    Link your WhatsApp Business account in Mindhunters dashboard
  </Step>
</Steps>

## 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

```text theme={null}
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

<Tabs>
  <Tab title="Via Dashboard">
    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)
  </Tab>

  <Tab title="Via Meta Business Manager">
    1. Log in to Meta Business Manager
    2. Navigate to WhatsApp Manager
    3. Go to **Message Templates**
    4. Create and submit templates
    5. Once approved, they'll appear in Mindhunters
  </Tab>
</Tabs>

### Template Categories

| Category           | Purpose              | Example Use Cases                                |
| ------------------ | -------------------- | ------------------------------------------------ |
| **Marketing**      | Promotional messages | Sales, offers, newsletters                       |
| **Utility**        | Transaction updates  | Order confirmations, shipping updates, reminders |
| **Authentication** | Verification codes   | OTP, password resets, login codes                |

<Note>
  Marketing templates have more restrictions and may have lower delivery rates. Use Utility or Authentication categories when possible.
</Note>

## Sending Messages via API

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

### Basic Example

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```

  ```javascript JavaScript theme={null}
  const sendWhatsAppMessage = async () => {
    const response = await fetch(
      'https://your-tenant.mindhunters.ai/api/v1/whatsapp/template',
      {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_API_TOKEN',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          agentId: 'agent-uuid-here',
          templateId: 'template-uuid-here',
          participant: {
            number: '+1234567890',
            name: 'John Doe'
          },
          parameters: ['John', 'March 15', '2:00 PM']
        })
      }
    );

    const data = await response.json();
    return data;
  };
  ```

  ```python Python theme={null}
  import requests

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

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()
  ```
</CodeGroup>

### With Media

Send templates with images or documents:

```javascript theme={null}
{
  "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

```text Template theme={null}
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

```text Template theme={null}
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

```text Template theme={null}
Name: shipping_update
Category: Utility

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

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

Track shipment: {{5}}
```

### Payment Reminders

```text Template theme={null}
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

<AccordionGroup>
  <Accordion title="Get Template Approval Early" icon="clock">
    * Submit templates for approval before you need them
    * Allow 24-48 hours for approval
    * Have backup templates ready
    * Keep rejected templates for reference
  </Accordion>

  <Accordion title="Personalize Messages" icon="user">
    * Use customer names
    * Include relevant order/account details
    * Make messages specific to the recipient
    * Avoid generic broadcasts
  </Accordion>

  <Accordion title="Respect Opt-Out" icon="ban">
    * Honor customer preferences
    * Provide easy opt-out options
    * Don't message opted-out contacts
    * Keep unsubscribe list updated
  </Accordion>

  <Accordion title="Timing Matters" icon="calendar">
    * Send messages during business hours
    * Consider recipient's timezone
    * Don't send too frequently
    * Space out campaigns appropriately
  </Accordion>

  <Accordion title="Monitor Delivery" icon="chart-line">
    * Track delivery and read rates
    * Monitor for failed deliveries
    * Check template performance
    * Optimize based on metrics
  </Accordion>
</AccordionGroup>

## 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:

```javascript Webhook Example theme={null}
{
  "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](/webhooks) 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 Rating | Daily Message Limit |
| -------------- | ------------------- |
| High           | 100,000 messages    |
| Medium         | 10,000 messages     |
| Low            | 1,000 messages      |

Maintain high quality by:

* Sending relevant messages
* Honoring opt-outs
* Using approved templates
* Avoiding spam reports

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference">
    View complete WhatsApp API docs
  </Card>

  <Card title="Webhooks" icon="webhook" href="/webhooks">
    Handle incoming messages
  </Card>

  <Card title="Campaigns" icon="bullhorn" href="/guides/services/campaigns">
    Create WhatsApp campaigns
  </Card>

  <Card title="Monitoring" icon="chart-line" href="/monitoring">
    Track message performance
  </Card>
</CardGroup>