# WhatsApp Broadcasts

> Send one approved WhatsApp template to up to 10,000 numbers from a CSV with Mojeeb Broadcasts, on the Professional plan: upload recipients, map template variables, send now, track Sent, Delivered, Read and Failed per recipient, retry failures and export the results.

A broadcast sends one approved WhatsApp template to a list of phone numbers you upload as a CSV file, from one of the agent's WhatsApp numbers: a promotion, a reminder, an announcement. Mojeeb sends it at once, tracks every recipient's status, and opens a conversation for each person, so replies land in your inbox and the agent answers them.

## Who can send a broadcast?

Broadcasts are part of the Professional plan and appear as **Broadcasts** in the sidebar; on other plans the page shows **Upgrade to unlock Broadcasts** with a **View plans** button. Owners and admins create broadcasts, retry failures and export results. Members can open the page and follow campaigns, but **Send Now** is refused with "Only admins can do this."

The agent also needs an active [WhatsApp](/docs/channels/whatsapp) connection and at least one [template](/docs/channels/whatsapp-templates) in **Approved** status; without one the wizard says **No approved templates found**.

## What do I need before I start?

An approved template and a CSV file of recipients. Templates may use body variables such as `{{1}}` or `{{customer_name}}`, which you fill from the CSV or with a fixed value. Broadcasts fill body variables only: the wizard still lists a template with a dynamic-URL button, an authentication button, a copy-code button or a variable in its text header, but every recipient then fails with "Message delivery failed. WhatsApp did not provide additional details." Send such templates one at a time from the WhatsApp page.

The CSV needs a header row with a `phone` column; `name` is optional, and any other column can feed a variable. Numbers must carry the country code: `+201001234567`, `201001234567` and `00201001234567` are all accepted, while `01001234567` is rejected as ambiguous. Media headers send the sample file uploaded when the template was created, the same for everyone.

## How do I create a broadcast?

Open [Broadcasts](https://dashboard.mojeeb.app/broadcasts), pick the agent at the top of the dashboard, and click **New Broadcast**. The wizard has four steps, and skips **Personalize** when the template has no variables. Nothing is sent until you click **Send Now** on the last step.

1. **Upload CSV** — Type a **Campaign Name**, prefilled with today's date, and drop the file on **Upload Recipients (CSV)**. Mojeeb reports how many numbers are **valid** and **invalid**, lists the invalid ones with the reason, and removes duplicates. Invalid rows are skipped, not blocking.
2. **Select Template** — Choose the **WhatsApp Connection** when the agent has more than one number, then the **Template** from the approved ones; the **Preview** shows its text.
3. **Personalize** — For each variable pick a column under **From CSV column** or choose **Set fixed value** and type the text for everyone. Named variables such as `customer_name` are matched to a column with the same name automatically; `{{1}}`-style variables need your choice. The preview steps through real recipients.
4. **Review & Send** — Check the campaign, template, category, language, recipient count and variable sources. A warning lists empty cells, which go out as a blank, and US numbers for marketing templates. Click **Send Now**; the toast **Broadcast started with N recipients** appears and the campaign page opens.

## What happens after I click Send Now?

Sending starts immediately and the campaign shows **Sending**; there is no schedule, draft, pause or cancel, so send a short test list first. Mojeeb sends several messages at a time within WhatsApp's rate limits, backing off when WhatsApp asks. Campaigns go out one after another, so a second campaign waits in **Sending** until the first finishes.

Every message that WhatsApp accepts opens a conversation on the Chats page, with the template as the first message from your business. When the customer replies, the agent answers like any other chat. A campaign that runs longer than 30 minutes stops with the status **Paused** and the remaining recipients **Pending**.

| Campaign status | Meaning |
|-----------------|---------|
| **Sending** | Messages are going out, or the campaign is waiting its turn |
| **Completed** | The run finished; some recipients may still have failed |
| **Failed** | Nothing could be sent, for example the WhatsApp connection was inactive |
| **Paused** | The run was interrupted; **Retry** resumes it if any recipient failed, otherwise send the remaining numbers as a new broadcast |

## How do I track delivery?

The Broadcasts list shows each campaign's template, recipient count, status, and a delivery line such as "120/150 sent (80% delivered)". Click a campaign for four cards, **Sent**, **Delivered**, **Read** and **Failed**, and a recipient table with **Phone**, **Name**, **Status**, **Sent At**, **Delivered At** and **Error**, filtered by **All**, **Sent**, **Delivered**, **Read** or **Failed**. Both pages update live.

| Recipient status | Meaning |
|------------------|---------|
| **Pending** | Not sent yet, or left over when a run was interrupted |
| **Sent** | WhatsApp accepted the message |
| **Delivered** | The message reached the customer's phone |
| **Read** | The customer opened it; needs read receipts on their side |
| **Failed** | WhatsApp refused it; the **Error** column says why |

## Why did a recipient fail?

The **Error** column shows WhatsApp's code and reason, such as "131026: Recipient is not a WhatsApp user". A number that is not on WhatsApp first shows **Sent**, then turns **Failed** when WhatsApp reports back. A failure without a code, "Message delivery failed. WhatsApp did not provide additional details.", usually means a template the broadcast cannot fill.

| Error | What to do |
|-------|------------|
| Recipient is not a WhatsApp user or has blocked this business number | Remove the number; it fails again on retry |
| Message blocked by WhatsApp's per-user frequency cap | The person received too many marketing messages recently; try later or use a Utility template |
| Too many messages sent to this recipient | Wait and retry |
| Template does not exist or has not been approved | Pick an approved template |
| Template was paused due to low quality | Edit the template and wait for approval |
| Template parameter count mismatch | Check that every variable has a value |
| Phone number is not registered on WhatsApp Cloud API | Finish the number's registration in Meta Business Manager |
| Rate limit exceeded | Retried automatically |
| Message delivery failed. WhatsApp did not provide additional details. | The template needs button or header values; send it from the WhatsApp page instead |

## How do I retry failed recipients?

Click **Retry** on the **Failed** card of the campaign page. It appears whenever a recipient failed, is disabled while the campaign is sending, puts every failed recipient back to **Pending**, and returns the campaign to **Sending**. It is also the only way to resume a **Paused** campaign, so a paused campaign with no failed recipient cannot be resumed; send its remaining numbers as a new broadcast. Numbers not on WhatsApp fail again.

## How do I export the results?

Click **Export CSV** on the campaign page; owners and admins can export, and members see a permission notice. The file follows the current filter and has the columns **#**, **Phone**, **Name**, **Status**, **Sent At (UTC)**, **Delivered At (UTC)**, **Read At (UTC)** and **Error**, opens in Excel with Arabic names intact, and is named after the campaign and the filter.

## What are the limits?

- **Recipients** — 1 to 10,000 per broadcast; duplicates are removed before sending.
- **Daily messaging tier** — WhatsApp allows each number 50 or 250 business-initiated conversations per day for a new or unverified business, then 1,000, 10,000, 100,000 or unlimited. A list larger than your tier is refused with "This audience size exceeds your WhatsApp daily messaging limit"; reduce the list or wait for Meta to raise the tier.
- **US numbers** — WhatsApp has not delivered marketing templates to +1 numbers since April 2025; the wizard warns and sends anyway.
- **Template lock** — While a campaign is sending, its template cannot be edited or deleted: "A broadcast is sending this template right now. Try again when it finishes."
- **Cost** — Broadcast messages do not count against your plan's monthly messages. Meta bills each business-initiated conversation to your WhatsApp Business Account, and the replies the agent sends afterwards count as ordinary Mojeeb messages.

## Common questions

### Do broadcast messages count against my message quota?

No. A broadcast uses none of your plan's monthly messages, however many recipients it has. Meta charges your WhatsApp Business Account per conversation, and when a customer replies, the agent's answers count like any other reply.

### Can I schedule a broadcast?

No. A broadcast goes out the moment you click **Send Now**. Prepare the CSV in advance and send it at the time you want.

### Can I stop a broadcast that is sending?

No. There is no pause or cancel once sending starts, so test with a short list first and keep marketing lists to people who agreed to hear from you.

### Does Mojeeb skip customers who asked to stop?

No. Mojeeb keeps no opt-out list, so remove those numbers from your CSV yourself. WhatsApp's own per-user cap may still hold a marketing message back.

### Can I send the same broadcast again?

Create a new broadcast with the same file. Numbers are only de-duplicated within one campaign, not across campaigns.

### Can I send an image or a PDF with the broadcast?

Yes, through a template with an image, video or document header. Every recipient receives the sample file uploaded when the template was created.

### Why were my numbers rejected?

They lack a country code, such as `01001234567`, or are not numbers at all. Write them as `+201001234567`; Excel's trailing `.00` is stripped automatically.

### Do replies reach my inbox?

Yes. Each sent message creates a conversation on the Chats page, and the agent answers the customer's reply unless you turn AI off for that chat.

## Related

- [WhatsApp Templates](/docs/channels/whatsapp-templates) — creating and approving the template a broadcast sends
- [WhatsApp](/docs/channels/whatsapp) — connecting the number
- [AI Conversations](/docs/features/ai-conversations) — where replies arrive
- [Plans & Pricing](/docs/billing/plans-and-pricing) — the Professional plan