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

{
  "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

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: "[phone]", name: "Mary", link: "https://shop.com/bf1" },
  { phone: "[phone]", name: "James", link: "https://shop.com/bf2" },
  { phone: "[phone]", 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

{
  "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.