# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.lipachat.com/guides/sending-broadcast-messages.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.