botserver/docs/src/chapter-06-gbdialog/templates/broadcast.md

Broadcast Template

The broadcast template enables mass messaging to contact lists, perfect for announcements, marketing campaigns, and bulk notifications through WhatsApp and other channels.

Topic: Mass Messaging & Announcements

This template is perfect for:

• Company-wide announcements
• Marketing campaigns
• Customer notifications
• Event reminders
• Newsletter distribution

The Code

PARAM message AS STRING LIKE "Hello {name}, how are you?" DESCRIPTION "Message to broadcast, supports {name} and {mobile} variables"
PARAM listfile AS STRING LIKE "broadcast.csv" DESCRIPTION "CSV file with contacts (name, mobile columns)"
PARAM filter AS STRING LIKE "status=active" DESCRIPTION "Filter condition for contact list" OPTIONAL

DESCRIPTION "Send broadcast message to a list of contacts from CSV file"

IF NOT listfile THEN
    listfile = "broadcast.csv"
END IF

IF filter THEN
    list = FIND listfile, filter
ELSE
    list = FIND listfile
END IF

IF UBOUND(list) = 0 THEN
    TALK "No contacts found in " + listfile
    RETURN 0
END IF

index = 1
sent = 0

DO WHILE index < UBOUND(list)
    row = list[index]

    msg = REPLACE(message, "{name}", row.name)
    msg = REPLACE(msg, "{mobile}", row.mobile)

    TALK TO row.mobile, msg
    WAIT 5

    WITH logEntry
        timestamp = NOW()
        user = USERNAME
        from = FROM
        mobile = row.mobile
        name = row.name
        status = "sent"
    END WITH

    SAVE "Log.xlsx", logEntry

    sent = sent + 1
    index = index + 1
LOOP

TALK "Broadcast sent to " + sent + " contacts."

RETURN sent

Sample Dialogs

These conversations show how the broadcast template works in real-world scenarios.

Dialog 1: Simple Broadcast

📢

Broadcast Bot

online

Today

Send a broadcast to all customers

10:00

Broadcast Bot

📢 Broadcast Setup

What message would you like to send?

You can use these variables:

• {name} - Contact's name

• {mobile} - Contact's phone

10:00

Hello {name}, we have exciting news! Our new product line is now available. Check it out at our store!

10:01

📋 Preview:

"Hello John, we have exciting news! Our new product line is now available. Check it out at our store!"

📊 Recipients: 156 contacts

Type SEND to start broadcast.

10:01

SEND

10:02

🚀 Broadcasting started...

Progress: 0/156

10:02

✅ Broadcast Complete!

📤 Sent: 154 messages

❌ Failed: 2 messages

📋 Log saved to Log.xlsx

10:15

Dialog 2: Filtered Broadcast

📢

Broadcast Bot

online

Send message only to VIP customers

14:30

🎯 Filtered Broadcast

I found 42 VIP customers.

What message would you like to send to them?

14:30

Dear {name}, as a valued VIP customer, you're invited to our exclusive preview sale this weekend. Use code VIP20 for 20% off!

14:31

📋 Preview:

"Dear Maria, as a valued VIP customer, you're invited to our exclusive preview sale this weekend. Use code VIP20 for 20% off!"

📊 Recipients: 42 VIP contacts

Type SEND to start broadcast.

14:31

Dialog 3: No Contacts Found

📢

Broadcast Bot

online

Broadcast to inactive users

16:00

⚠️ No contacts found in broadcast.csv matching filter "status=inactive"

Would you like to:

1. Try a different filter

2. Send to all contacts

3. Upload a new contact list

16:00

Keywords Used

Keyword	Purpose
PARAM	Define input parameters with descriptions
DESCRIPTION	Tool description for AI
FIND	Query contacts from CSV file
REPLACE	Substitute variables in message template
TALK TO	Send message to specific phone number
WAIT	Delay between messages (rate limiting)
SAVE	Log each message to spreadsheet
RETURN	Return count of sent messages

How It Works

1. Load Contacts: FIND retrieves contacts from CSV with optional filter
2. Validate List: Checks if contacts were found
3. Loop Through Contacts: Iterates through each contact
4. Personalize Message: REPLACE substitutes {name} and {mobile}
5. Send Message: TALK TO delivers to each phone number
6. Rate Limiting: WAIT 5 pauses 5 seconds between messages
7. Log Operation: Each send is recorded in Log.xlsx
8. Report Results: Returns total messages sent

Contact List Format

Your CSV file should have these columns:

name,mobile,status,segment
John Smith,+5511999999999,active,regular
Maria Garcia,+5521888888888,active,vip
Carlos Santos,+5531777777777,inactive,regular
Ana Lima,+5541666666666,active,vip

Column	Required	Description
name	Yes	Contact's display name
mobile	Yes	Phone in international format
status	No	For filtering (active/inactive)
segment	No	For targeting (vip/regular)

Customization Ideas

Add Message Templates

ADD TOOL "broadcast"
ADD TOOL "list-templates"
ADD TOOL "create-template"

' Load saved templates
templates = FIND "message_templates.csv"

TALK "Available templates:"
FOR EACH template IN templates
    TALK "• " + template.name + ": " + LEFT(template.message, 50) + "..."
NEXT

TALK "Which template would you like to use?"
HEAR templateName

selected = FIND "message_templates.csv", "name = '" + templateName + "'"
message = selected.message

Add Scheduling

PARAM schedule_time AS STRING LIKE "2025-01-20 09:00" DESCRIPTION "When to send (optional)"

IF schedule_time THEN
    SET SCHEDULE schedule_time
    
    ' Store broadcast details for later
    SET BOT MEMORY "scheduled_message", message
    SET BOT MEMORY "scheduled_list", listfile
    SET BOT MEMORY "scheduled_filter", filter
    
    TALK "📅 Broadcast scheduled for " + schedule_time
    TALK "I'll send to " + UBOUND(list) + " contacts at that time."
    RETURN 0
END IF

Add Progress Updates

total = UBOUND(list)
checkpoints = [25, 50, 75, 100]

DO WHILE index <= total
    ' ... send message ...
    
    ' Check progress
    percent = INT((index / total) * 100)
    IF INARRAY(percent, checkpoints) THEN
        TALK "📊 Progress: " + percent + "% (" + index + "/" + total + ")"
    END IF
    
    index = index + 1
LOOP

Add Opt-Out Handling

' Check if contact has opted out
optouts = FIND "optouts.csv"

DO WHILE index <= UBOUND(list)
    row = list[index]
    
    ' Skip opted-out contacts
    IF FIND("optouts.csv", "mobile = '" + row.mobile + "'") THEN
        WITH logEntry
            mobile = row.mobile
            status = "skipped-optout"
        END WITH
        SAVE "Log.xlsx", logEntry
        index = index + 1
        CONTINUE
    END IF
    
    ' ... send message ...
LOOP

Add Media Support

PARAM image AS STRING LIKE "promo.jpg" DESCRIPTION "Image to include (optional)"

IF image THEN
    msg = msg + "\n[Image: " + image + "]"
    TALK TO row.mobile, msg, image
ELSE
    TALK TO row.mobile, msg
END IF

Best Practices

Message Content

1. Personalize: Always use {name} for a personal touch
2. Be Concise: Keep messages short and clear
3. Clear CTA: Include a clear call-to-action
4. Identify Yourself: Make sure recipients know who's messaging

Compliance

1. Consent Required: Only message contacts who opted in
2. Easy Opt-Out: Include unsubscribe instructions
3. Respect Hours: Don't send late at night
4. Honor Limits: WhatsApp has daily messaging limits

Performance

1. Rate Limiting: Keep 5+ second delays to avoid blocks
2. Batch Processing: For large lists, consider batching
3. Error Handling: Log and handle failed sends
4. Monitor Results: Check logs for delivery issues

Logging Structure

The Log.xlsx file tracks all broadcast activity:

Column	Description
timestamp	When message was sent
user	Who initiated the broadcast
from	Sender identifier
mobile	Recipient phone number
name	Recipient name
status	sent/failed/skipped
error	Error message if failed

Related Templates

• announcements.bas - Company announcements system
• whatsapp.bas - WhatsApp-specific features
• store.bas - E-commerce with customer notifications

---