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

# Integrate and Broadcast on WhatsApp with Botsify API

> Connect your Botsify bot to WhatsApp, create and manage message templates, send broadcasts, and retrieve detailed delivery reports via the API.

WhatsApp is one of the highest-engagement messaging channels in the world, and Botsify gives you a first-class API for reaching your subscribers there. You can define reusable message templates, broadcast them to lists of users, and pull detailed delivery reports — all through a handful of straightforward API calls. This guide walks you through each step.

> [!NOTE]
>
> **WhatsApp requires pre-approved message templates.** Unlike SMS or Messenger, WhatsApp Business only allows you to initiate conversations using templates that have been reviewed and approved by Meta. You must create a template through the Botsify API (or dashboard) and wait for approval before you can send it to users. Session replies — messages sent within an active 24-hour conversation window — do not require a template.

## Overview

The WhatsApp workflow in Botsify has four stages:

1. **Create templates** — define the message structure (text, media, buttons) and submit for approval.
2. **Fetch templates** — retrieve your approved and pending templates to use in broadcasts.
3. **Send a broadcast** — dispatch a template message to one or more recipients.
4. **Pull a report** — measure delivery, read rates, and failures over a date range.

***

## Step 1 — Fetch existing templates

Before creating a new template, check what you already have. `GET /api/v1/media-block/fetch` returns your full list of WhatsApp message templates.

```bash theme={null}
curl --request GET \
  --url https://app.botsify.com/api/v1/media-block/fetch \
  --header 'Authorization: Bearer <YOUR_API_KEY>'
```

The response is an array of template objects. Each template includes its name, approval status, and content structure. Note the template name of any approved templates — you will reference them when sending a broadcast.

***

## Step 2 — Create a template

Use `POST /api/v1/media-block/create` to submit a new WhatsApp message template for approval. You can optionally append the template type to the path (e.g. `POST /api/v1/media-block/create/text` or `POST /api/v1/media-block/create/media`) to specify the template category.

```bash theme={null}
curl --request POST \
  --url https://app.botsify.com/api/v1/media-block/create \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --data '{
    "name": "order_shipped_v1",
    "language": "en_US",
    "category": "UTILITY",
    "components": [
      {
        "type": "BODY",
        "text": "Hi {{1}}, your order {{2}} has shipped and will arrive by {{3}}."
      },
      {
        "type": "FOOTER",
        "text": "Reply STOP to unsubscribe."
      }
    ]
  }'
```

After submission, the template enters a review queue. Approval typically takes a few minutes to a few hours depending on Meta's review process. Poll `GET /api/v1/media-block/fetch` to check when the status changes to `APPROVED`.

***

## Step 3 — Send a single broadcast

Once you have an approved template, use `POST /api/v1/whatsapp/single-message-send` to dispatch it to one or more recipients.

```bash theme={null}
curl --request POST \
  --url https://app.botsify.com/api/v1/whatsapp/single-message-send \
  --header 'Content-Type: application/json' \
  --data '{
    "apikey": "<YOUR_API_KEY>",
    "type": "template",
    "template": "order_shipped_v1",
    "users": [
      { "phone": "+14155552671" },
      { "phone": "+14155552672" }
    ],
    "template_data": {
      "1": "Sarah",
      "2": "#4521",
      "3": "Friday, Jan 17"
    }
  }'
```

**Request body fields**

| Field | Type | Required | Description |
| - | - | - | - |
| `apikey` | string | ✅ | Your Botsify API key |
| `type` | string | ✅ | Message type — use `"template"` for WhatsApp template messages |
| `template` | string | ✅ | The name of the approved template to send |
| `users` | array | ✅ | Array of recipient objects, each containing a `phone` number in E.164 format |
| `template_data` | object | ✅ | Key-value pairs mapping template variable positions (e.g. `"1"`, `"2"`) to their runtime values |

***

## Step 4 — Pull a broadcast report

After sending, retrieve delivery metrics for any date range using `POST /api/v1/whatsapp-broadcast-report`.

```bash theme={null}
curl --request POST \
  --url https://app.botsify.com/api/v1/whatsapp-broadcast-report \
  --header 'Content-Type: application/json' \
  --data '{
    "apikey": "<YOUR_API_KEY>",
    "start_date": "2025-01-01",
    "end_date": "2025-01-31"
  }'
```

**Request body fields**

| Field | Type | Required | Description |
| - | - | - | - |
| `apikey` | string | ✅ | Your Botsify API key |
| `start_date` | string | ✅ | Report start date in `YYYY-MM-DD` format |
| `end_date` | string | ✅ | Report end date in `YYYY-MM-DD` format |

The response includes broadcast-level statistics for all WhatsApp sends that occurred within the specified window — including sent counts, delivery confirmations, and read receipts where available.

***

## Quick-reference summary

> **Fetch templates**
>
> `GET /api/v1/media-block/fetch`\
> List all your WhatsApp templates and their approval status.

> **Create template**
>
> `POST /api/v1/media-block/create`\
> Submit a new template for Meta review and approval.

> **Send broadcast**
>
> `POST /api/v1/whatsapp/single-message-send`\
> Dispatch an approved template to one or more phone numbers.

> **Broadcast report**
>
> `POST /api/v1/whatsapp-broadcast-report`\
> Retrieve delivery and engagement stats for a date range.

## Next steps

* **Measure overall engagement** — combine WhatsApp broadcast data with your bot's full message stats in [Analytics](/guides/analytics).
* **Trigger broadcasts from your backend** — chain the send endpoint into your order management, CRM, or notification system using the same API key pattern.


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