# WhatsApp Overview

> WhatsApp messaging overview: rich media, templates, buttons, lists and the 24-hour conversation window.

WhatsApp Business API enables high-engagement messaging with rich features like images, documents, interactive buttons, and more.

## When to Use WhatsApp

- **Customer support**: Rich media and quick replies
- **Marketing campaigns**: Higher open rates than SMS (90%+ vs 20%)
- **Order updates**: Detailed information with images and tracking
- **International messaging**: Often cheaper than SMS

## Basic WhatsApp Message

```typescript
const result = await zavu.messages.send({
  to: "+14155551234",
  text: "Hello from Zavu!",
  channel: "whatsapp",
});
```

```bash
curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "text": "Hello from Zavu!",
    "channel": "whatsapp"
  }'
```

## The 24-Hour Conversation Window

WhatsApp enforces a conversation window that determines what types of messages you can send:

```
User sends message → 24-hour window opens → Send any message type
                                          ↓
                     Window expires → Template messages only
```

| Message Type | Within 24h | After 24h |
|--------------|------------|-----------|
| Text (session) | Yes | No |
| Media (session) | Yes | No |
| Interactive (session) | Yes | No |
| Template (pre-approved) | Yes | Yes |

> **Warning:**
> Sending a session message outside the 24-hour window will fail. Use templates for messages outside the window.

## Message Types

WhatsApp supports rich message formats beyond plain text:

### Session Messages (within 24h window)

| Type | Use Case | Guide |
|------|----------|-------|
| Text | Simple messages | [Text](https://www.zavu.dev/docs/guides/whatsapp/messages/text) |
| Image | Product photos, receipts | [Image](https://www.zavu.dev/docs/guides/whatsapp/messages/image) |
| Video | Tutorials, promotions | [Video](https://www.zavu.dev/docs/guides/whatsapp/messages/video) |
| Audio | Voice notes, announcements | [Audio](https://www.zavu.dev/docs/guides/whatsapp/messages/audio) |
| Document | PDFs, invoices | [Document](https://www.zavu.dev/docs/guides/whatsapp/messages/document) |
| Sticker | Engagement, branding | [Sticker](https://www.zavu.dev/docs/guides/whatsapp/messages/sticker) |
| Location | Store location, delivery | [Location](https://www.zavu.dev/docs/guides/whatsapp/messages/location) |
| Contact | Share contact info | [Contact](https://www.zavu.dev/docs/guides/whatsapp/messages/contact) |
| Buttons | Quick actions | [Buttons](https://www.zavu.dev/docs/guides/whatsapp/messages/buttons) |
| List | Multiple options | [List](https://www.zavu.dev/docs/guides/whatsapp/messages/list) |
| Reaction | Acknowledge messages | [Reaction](https://www.zavu.dev/docs/guides/whatsapp/messages/reaction) |
| Typing indicator | Show typing dots while preparing a reply | [Typing](https://www.zavu.dev/docs/guides/whatsapp/messages/typing-indicator) |

### Template Messages (anytime)

Pre-approved messages that can be sent outside the 24-hour window. See [Templates Guide](https://www.zavu.dev/docs/guides/whatsapp/templates/sending).

## Delivery Status

WhatsApp provides detailed delivery tracking:

| Status | Description |
|--------|-------------|
| `queued` | Message accepted by Zavu |
| `sent` | Sent to WhatsApp servers |
| `delivered` | Delivered to user's device |
| `read` | User opened the message |
| `failed` | Delivery failed |

> **Tip:**
> WhatsApp is the only channel that provides "read" receipts, useful for tracking engagement.

## Quality Rating

Meta tracks your messaging quality. Maintain good standing by:

1. **Getting opt-in consent** before messaging
2. **Respecting user preferences** - stop messaging users who don't respond
3. **Sending relevant content** - avoid spam-like messages
4. **Responding promptly** - engage within the 24-hour window

> **Warning:**
> Low quality ratings can result in reduced messaging limits or account suspension.

## Common Errors

| Error | Cause | Solution |
|-------|-------|----------|
| `Outside 24h window` | Session expired | Use a template message |
| `Template not approved` | Template pending/rejected | Wait for approval or fix issues |
| `Invalid phone format` | Wrong number format | Use E.164 format (+country code) |
| `User not on WhatsApp` | Recipient doesn't have WhatsApp | Fall back to SMS |
| `Rate limited` | Too many messages too fast | Slow down sending rate |

## Next Steps

- [Text Messages](https://www.zavu.dev/docs/guides/whatsapp/messages/text) - Basic text with formatting
- [Image Messages](https://www.zavu.dev/docs/guides/whatsapp/messages/image) - Send photos and images
- [Buttons](https://www.zavu.dev/docs/guides/whatsapp/messages/buttons) - Interactive quick replies
- [Templates](https://www.zavu.dev/docs/guides/whatsapp/templates/sending) - Pre-approved messages for any time