> For the complete documentation index, see [llms.txt](https://docs.lipachat.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lipachat.com/guides/sending-broadcast-messages.md).

# Sending Broadcast Messages

Broadcasts allow you to send a WhatsApp message to many customers at once using a **WhatsApp-approved template**.

> **Free-form vs Templates**\
> WhatsApp requires message templates for any business-initiated communication that occurs outside of an active session. A session automatically begins whenever a user sends a message to your WhatsApp number and remains open for 24 hours. During an active session, you can exchange free-form messages without additional constraints.

***

### Broadcast Flow Overview

1. **Verify the template exists**, or create it if missing
2. **Loop through your recipients** and send the template via API
3. **Receive customer replies** through the Incoming Messages Webhook
4. **Receive delivery/read status** through the Status Webhook

### 1. Verify or Create a Template

Before broadcasting, make sure the template already exists in your Lipachat workspace.

If missing, create a new template via:

🔗 **Creating a Template**\
<https://docs.lipachat.com/api/editor/creating-a-template>

Template approval is handled by Meta and is **automated**, typically completing **within 5 minutes**.

**Example template content:**

```
Dear {{1}} we have an offer for you this Black Friday {{2}}
```

Placeholders (`{{1}}`, `{{2}}`) will be replaced using your request payload.

***

### 2. Sending the Template to Multiple Customers

Use the Template Send API endpoint:

🔗 **Send Template**\
<https://docs.lipachat.com/api/editor/send-template>

API URL used for sending:

```
POST https://gateway.lipachat.com/api/v1/whatsapp/template
```

#### Example Request Payload

```json
{
  "messageId": "d13ce19b-678f-4a94-a910-441cfbb25b9b",
  "to": "PHONE_NUMBER",
  "from": "BUSINESS_PHONE_NUMBER",
  "template": {
    "name": "offer_830",
    "languageCode": "en",
    "components": {
      "header": {
        "type": "TEXT",
        "parameter": "Discounts"
      },
      "body": {
        "placeholders": [
          "John",
          "https://shop.com/offer123"
        ]
      }
    }
  }
}
```

***

#### JavaScript Example: Looping Through Recipients

Below is a simple Node.js script that:

* Reads a list of `{ phone, name, link }`
* Replaces `{{1}}` with the customer’s name
* Replaces `{{2}}` with their personalised link
* Sends the template message to each contact

```javascript
import fetch from "node-fetch";

const API_KEY = "YOUR_LIPACHAT_API_KEY";
const API_URL = "https://gateway.lipachat.com/api/v1/whatsapp/template";

const recipients = [
  { phone: "+254700000001", name: "Mary", link: "https://shop.com/bf1" },
  { phone: "+254700000002", name: "James", link: "https://shop.com/bf2" },
  { phone: "+254700000003", name: "Aisha", link: "https://shop.com/bf3" }
];

async function sendTemplateMessage(recipient) {
  const payload = {
    messageId: crypto.randomUUID(),
    to: recipient.phone,
    from: "YOUR_WHATSAPP_NUMBER",
    template: {
      name: "black_friday_offer",
      languageCode: "en",
      components: {
        header: {
          type: "TEXT",
          parameter: "Black Friday Offer"
        },
        body: {
          placeholders: [
            recipient.name,  // {{1}}
            recipient.link   // {{2}}
          ]
        }
      }
    }
  };

  const response = await fetch(API_URL, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": API_KEY
    },
    body: JSON.stringify(payload)
  });

  const result = await response.json();
  console.log(`Sent to ${recipient.phone}:`, result);
}

async function sendBroadcast() {
  for (const r of recipients) {
    try {
      await sendTemplateMessage(r);
    } catch (err) {
      console.error(`Failed to send to ${r.phone}`, err);
    }
  }
}

sendBroadcast();
```

***

### 3. Receiving Customer Replies

When a customer responds to your broadcast, Lipachat immediately sends the message payload to your Incoming Messages Webhook.

Refer to:

🔗 **Webhooks Reference**\
<https://docs.lipachat.com/api/webhooks>

#### Example Incoming Message Payload

```json
{
  "messageId": "c94ced08-5f40-46b7-a88d-7d4fbe113fe9",
  "from": "CUSTOMER_PHONE_NUMBER",
  "to": "WHATSAPP_NUMBER",
  "profileName": "CUSTOMER_NAME",
  "type": "TEXT",
  "text": "I am interested in this product, do you offer delivery services"
}
```

Use this data to:

* Track customer interest
* Register opt-outs (STOP, CANCEL, etc.)
* Trigger workflows (e.g., assign agent, create order, qualify lead)

***

### 4. Receiving Delivery & Read Status

As WhatsApp processes your outbound messages, Lipachat will send status updates to your Status Webhook.

Refer to:

🔗 **Webhooks Reference**\
<https://docs.lipachat.com/api/webhooks>

Common statuses:

* `delivered`
* `read`
* `failed`

These events allow you to build reporting dashboards or retry failed messages.

***

### Best Practices

* Ensure each recipient has all required placeholders before sending.
* For large lists, batch sends to avoid rate limiting.
* Log all incoming messages + statuses for analytics.
* Immediately honor STOP/opt-out replies.