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

# Messaging

> Send and manage WhatsApp messages including text, images, documents, audio, video, stickers, contacts, location, and interactive messages through the Zeplo API.

# Messaging

Zeplo provides a unified messaging API that lets you send every type of WhatsApp message your business needs. Whether you are sending transactional alerts, marketing promotions, or rich media content, the messaging endpoint handles it all. Supported message types include plain text, image, document, audio, video, sticker, contacts, location, and interactive messages with buttons and lists.

> **[Template Messages](https://docs.zeplo.ai/docs/features/templates.md)**
>
> Send pre-approved WhatsApp template messages for notifications, marketing, and authentication outside the 24-hour window.

> **Reply Messages**
>
> Respond directly to incoming customer messages within the 24-hour conversation window using free-form text and media.

> **Message Status**
>
> Track the lifecycle of every message with real-time status updates — sent, delivered, read, and failed.

> **Media Messages**
>
> Attach images, documents, audio, video, and stickers to your messages with automatic upload and hosting.

## Basic Usage

**JavaScript/TypeScript**

```typescript theme={null}
import { Zeplo } from "@zeplo/sdk";

const zeplo = new Zeplo({ apiKey: process.env.ZEPLO_API_KEY });

// Send a template message
const templateMsg = await zeplo.messages.sendTemplate({
  to: "+1234567890",
  templateName: "welcome_message",
  language: "en",
  components: [
    {
      type: "body",
      parameters: [
        { type: "text", text: "John" },
      ],
    },
  ],
});

// Send a reply (free-form, within 24h window)
const replyMsg = await zeplo.messages.send({
  to: "+1234567890",
  type: "text",
  text: { body: "Thank you for reaching out! How can we help?" },
  replyToMessageId: "wamid.previous_message_id",
});

console.log(templateMsg.messageId, replyMsg.messageId);
```

**Python**

```python theme={null}
import os
from zeplo import Zeplo

zeplo = Zeplo(api_key=os.environ["ZEPLO_API_KEY"])

# Send a template message
template_msg = zeplo.messages.send_template(
    to="+1234567890",
    template_name="welcome_message",
    language="en",
    components=[
        {
            "type": "body",
            "parameters": [
                {"type": "text", "text": "John"},
            ],
        },
    ],
)

# Send a reply (free-form, within 24h window)
reply_msg = zeplo.messages.send(
    to="+1234567890",
    type="text",
    text={"body": "Thank you for reaching out! How can we help?"},
    reply_to_message_id="wamid.previous_message_id",
)

print(template_msg.message_id, reply_msg.message_id)
```

> [!NOTE]
>
> You can also send messages via cURL. All endpoints accept `Authorization: Bearer <api_key>` and `Content-Type: application/json` headers.

## Message Types

| Type | Description | Key Fields |
| - | - | - |
| `text` | Plain text message | `text.body` |
| `image` | Image with optional caption | `image.link` or `image.id`, `image.caption` |
| `document` | PDF or other document | `document.link` or `document.id`, `document.filename` |
| `audio` | Audio file | `audio.link` or `audio.id` |
| `video` | Video with optional caption | `video.link` or `video.id`, `video.caption` |
| `sticker` | WebP sticker image | `sticker.link` or `sticker.id` |
| `contacts` | One or more contact cards | `contacts[].name`, `contacts[].phones` |
| `location` | GPS location pin | `location.latitude`, `location.longitude`, `location.name` |
| `interactive` | Buttons or list menus | `interactive.type`, `interactive.body`, `interactive.action` |

## Best Practices

> Free-form messages can only be sent within **24 hours** of the last customer message. After the window closes you must use a pre-approved template. Plan your automation flows to send critical information early in the conversation and fall back to templates when the window expires.

> Every template must be submitted to Meta for approval before it can be used. Include clear, concise copy and avoid misleading content. Templates are categorized as **MARKETING**, **UTILITY**, or **AUTHENTICATION** — pick the right category to speed up approval.

> WhatsApp enforces file size limits per media type: images up to **5 MB**, documents up to **100 MB**, audio up to **16 MB**, video up to **16 MB**, and stickers up to **100 KB**. Always compress assets before uploading to avoid delivery failures.

> Use WhatsApp formatting to improve readability: `*bold*`, `_italic_`, `~strikethrough~`, and `` `monospace` ``. For longer content, consider using interactive list messages to keep the UI clean and actionable.

> **[API Reference: Send Message](https://docs.zeplo.ai/docs/api-reference/messages/send-message.md)**
>
> Explore the full request schema, response format, and error codes for the send message endpoint.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.