botserver/templates/broadcast.gbai/broadcast.gbkb/broadcast-guide.md

Broadcast Messaging Guide

Overview

The Broadcast feature allows you to send messages to multiple contacts simultaneously using WhatsApp or other messaging channels. This is ideal for announcements, marketing campaigns, and bulk notifications.

How to Send a Broadcast

Basic Broadcast

To send a broadcast message, you need:

1. A message template with optional personalization variables
2. A CSV file containing your contact list

Message Variables

You can personalize messages using these variables:

• {name} - Replaced with the contact's name
• {mobile} - Replaced with the contact's phone number

Example:

Hello {name}, we have exciting news to share with you!

Contact List Format

Your CSV file should have the following columns:

• name - Contact's name
• mobile - Phone number in international format (e.g., +5511999999999)
• Additional columns can be used for filtering

Example broadcast.csv:

name,mobile,status
John Smith,+5511999999999,active
Maria Garcia,+5521888888888,active
Carlos Santos,+5531777777777,inactive

Filtering Contacts

You can filter your contact list using conditions:

• status=active - Only send to active contacts
• region=south - Filter by custom fields
• Multiple filters can be combined

Best Practices

Message Content

1. Keep it concise - Short messages have higher engagement
2. Personalize - Use {name} to make messages feel personal
3. Clear call-to-action - Tell recipients what to do next
4. Timing - Send during appropriate business hours

Contact Management

1. Clean your list - Remove invalid numbers regularly
2. Respect opt-outs - Remove contacts who don't want messages
3. Update regularly - Keep contact information current
4. Segment audiences - Use filters for targeted messaging

Compliance

1. Get consent - Only message contacts who opted in
2. Identify yourself - Make clear who is sending the message
3. Provide opt-out - Include instructions to unsubscribe
4. Follow local laws - LGPD, GDPR, TCPA requirements apply

Rate Limits

To prevent spam detection and ensure delivery:

• Messages are sent with a 5-second delay between each
• WhatsApp Business API limits apply
• Large broadcasts may take time to complete

Logging and Tracking

All broadcast operations are logged to Log.xlsx with:

• Timestamp
• User who initiated the broadcast
• Recipient mobile number
• Recipient name
• Delivery status

Troubleshooting

Messages Not Sending

• Verify phone numbers are in international format
• Check that the CSV file exists and has correct columns
• Ensure the bot has messaging permissions

Some Contacts Skipped

• Contact may have blocked the number
• Phone number format may be incorrect
• WhatsApp account may not exist for that number

Slow Delivery

• Large lists take time due to rate limiting
• This is intentional to prevent spam flags
• Check Log.xlsx for progress

Frequently Asked Questions

Q: How many contacts can I message at once? A: There's no hard limit, but larger lists will take longer due to rate limiting.

Q: Can I schedule broadcasts for later? A: Yes, use scheduled jobs to set up future broadcasts.

Q: Will I know if messages were delivered? A: The log file tracks send status. Delivery confirmation depends on the messaging platform.

Q: Can I send images or files? A: The basic broadcast sends text. For media, use dedicated media broadcast tools.

Q: How do I stop a broadcast in progress? A: Contact an administrator to stop the process if needed.