Broadcasts

What is a Broadcast?

• Only Meta-approved templates can be used (required for business-initiated conversations).
• Can be launched immediately or scheduled for any future date and time.
• Scheduled broadcasts launch automatically — no manual action needed when the time arrives.
• Built-in real-time delivery tracking: sent, delivered, read, failed, and queued counts update live.
• Contacts who have opted out are automatically excluded.

Creating a Broadcast

Broadcasting on Telegram

• It goes to everyone who has started a chat with your bot. People who type STOP to the bot, and blocked contacts, are left out.
• There is no 24-hour window and no template — write any message and send it whenever you like. Telegram doesn't charge for it.
• Choose what to send: a message (with a picture, video, GIF, file, music, voice note or sticker), an album of 2–10 pictures and videos, a poll or quiz, a location pin, a named place, a contact card, or a dice / game.
• Personalise it with {{contact.name}} and the other contact details.
• Add up to 10 buttons, one to three per row. A link button opens a web page; a reply button sends its label back as the person's answer, which shows in Live Chat and counts as a click.
• Poll votes show in Live Chat and count as replies — unless you turn on anonymous voting, which Telegram never reports to your bot.
• Choose all your Telegram contacts, a tag, or a saved segment. On Telegram a segment's rules are checked against each Telegram contact.
• Google Sheets, Google Contacts and Zoho lists can't be used: they are phone numbers, and a bot can only message people who have written to it first.
• The report shows sent, delivered, failed, replied and clicked. Telegram doesn't tell bots when a message is read, so the read figure is left blank and there is no A/B test.
• If someone has blocked your bot, their message fails straight away with that reason — it isn't retried.

Real-Time Broadcast Tracker

• Running broadcasts refresh every 4 seconds.
• Scheduled broadcasts refresh every 10 seconds (so you see the moment they launch).
• Paused broadcasts refresh every 30 seconds.
• The Message Log tab shows per-contact status (Queued, Sent, Delivered, Read, Failed) and any error detail.
• Filter the log by status to quickly find failed messages.

Broadcast Statuses

Pausing and Resuming

Retrying Failed Messages

URL Button Variables

• Map the variable to a contact field or static value just like body variables.
• If the resolved value is empty for a contact, the button component is omitted for that recipient rather than sending an invalid URL.
• Values are URL-encoded automatically — spaces and special characters are handled.

Analytics

• Total — audience size at the time the broadcast was launched.
• Queued — messages waiting to be sent (decreases as broadcast progresses).
• Sent — dispatched to WhatsApp's API successfully.
• Delivered — reached the recipient's device (double grey tick).
• Read — opened by the recipient (double blue tick).
• Failed — permanently failed after all retry attempts.

Sending via API

POST /api/v1/broadcasts/send
Content-Type: application/json
Authorization: Bearer motherbot_xxx

{
  "name": "Order Dispatch — June batch",
  "templateName": "order_confirmation",
  "languageCode": "en_US",

  // These values apply to every recipient. No need to repeat them.
  "commonVariables": {
    "1": "MotherBot Store",
    "3": "support@mystore.com"
  },

  "headerMediaUrl": "https://cdn.mystore.com/banner.jpg",
  "rateLimitPerSecond": 10,

  "recipients": [
    // {{2}} (order ID) is different per recipient — only that key is provided
    { "to": "919876543210", "name": "John Smith",   "variables": { "2": "ORDER-9912" } },
    { "to": "918765432109", "name": "Priya Sharma", "variables": { "2": "ORDER-9913" } },
    // No variables at all — all three placeholders come from commonVariables
    { "to": "917654321098", "name": "Ravi Kumar" }
  ]
}

# Response 201
{
  "success": true,
  "data": {
    "campaignId": "665d4c...",
    "status": "running",
    "total": 3,
    "rateLimitPerSecond": 10,
    "etaSeconds": 1,
    "etaText": "~1 second"
  }
}

• Up to 100,000 recipients per request. Duplicate phone numbers are automatically deduplicated.
• templateId (MongoDB ID) or templateName + languageCode — both are accepted.
• Templates must be APPROVED. Pending or rejected templates return HTTP 400.
• rateLimitPerSecond defaults to 3 and is capped at 80 (Meta limit).
• Large lists are chunked and enqueued in the background — the API returns immediately with a campaignId.

Budget and approvals

A monthly spend budget

• Alerts at thresholds you choose, to recipients you choose. An ACTUAL alert fires when you have spent that much; a FORECAST alert fires when your current daily rate is heading there by month end.
• Each threshold can add its own recipients on top of a list that receives everything — so finance can be told at 100% and you at 50%.
• Raising the budget mid-month re-arms every alert at the new figure, rather than silencing the ones that already fired.
• Enter your own per-message rates so estimates match what you are really billed. What Meta charges depends on your country; what your gateway charges depends on your contract.
• Optionally stop sending at a line you set — 100% of the budget, or higher if you want a buffer.

Approval before a bulk send

• Hold on recipient count, on estimated cost, or once the monthly budget is spent — any combination.
• It covers every way a send can start: the dashboard, the mobile app, the API, the Chrome extension, the Google Sheets and Excel add-ins, the Zoho CRM widget and the WordPress plugin.
• The Approvals screen shows who asked, how many people it reaches, what it will cost, the template, a few recipients and why it was held. Approvers are emailed and pushed; the requester is emailed the answer.
• Grant a staff member the Approve Broadcasts & Bulk Sends permission to let them decide. It is deliberately separate from managing broadcasts — the person who starts a send is who the queue exists to review.
• A staff member cannot approve their own request.

What an approved send does

• An approved bulk send always resumes through the queue and comes back with a batch id, even when the original request was small enough to have been sent inline — by the time somebody says yes, there is no open request left to answer.
• A release that is interrupted resumes from where it stopped, not from the beginning, and nobody is messaged twice.
• If the queue is briefly unavailable when you approve, your decision still stands — the send starts on its own as soon as it recovers, and the screen says so rather than pretending it went out.

Best Practices

• Always personalize with contact name or a custom field — broadcasts with personalization see 30–40% higher read rates.
• Send during business hours in your audience's timezone.
• Keep your opt-out rate below 2% to protect your Meta quality rating.
• Test with a small tag group (10–20 contacts) before launching to your full list.
• Use custom fields (cf1–cf10) to store per-contact values like order IDs, invoice numbers, or plan names for truly personalized sends.