Audience messages

Most scheduled tasks message one contact. An Audience Message messages everyone in a data table who matches your filters — one message per matching row, on WhatsApp or Telegram.

Create one from the agent's Scheduled Tasks tab, the same place as any other task, by choosing the Audience Message action.

How it differs from a single-contact task

Because no model runs, an audience message says exactly what you wrote. It is a way to reach a list, not a way to hold a conversation — though if a recipient replies, the agent picks up the conversation the message opened, with the campaign for context, rather than starting cold.

There is no "payment reminder" or "birthday" feature. Those are a filter and a template, and building them is the point.

Choosing who receives it

Pick a Data table, then add Filters. Everyone in the table who matches them all will be messaged. Only tables the agent has read permission on are offered — see permissions if the table you want is missing.

Filter values can use date tokens, resolved against the task's timezone on the day it runs:

So "invoices due in a week" is due_date is {{today+7d}}, and "birthdays today" is birthday is {{today:MM-DD}} against a column holding MM-DD.

Which column can be addressed

Send to picks the column holding each recipient's address. Only two column types can be messaged, and which one depends on the channel.

If your table stores numbers in a phone column, add a WhatsApp ID column and populate it with the digits-only form. See field types.

Rows that match your filters but have nothing in the Send to column are skipped, and counted separately in the preview.

Addressing through a linked table

The address does not have to live on the table you are filtering. If your table has a relation column linking each row to one record in another table — a Payments table where every payment links to a Contacts record — Send to also offers that table's columns, shown as Contact → WhatsApp ID.

That is what lets you filter payments and message people: the filters run on the payments row, the message goes to the number on the linked contact. You do not have to copy the number onto every payment, so it stays correct when the customer changes it.

Two limits:

• The relation must link to one record, not many. A relation that holds several records names no single recipient, so it is not offered.
• Filters still run on the table you picked. You cannot filter on a linked table's columns — filter on Payments, address through Contacts.

A payment whose relation is empty, or points at a record that has since been deleted, is skipped and counted separately in the preview from rows whose contact simply has no WhatsApp ID. The two have different fixes: link the record, or fill in the number.

A table with no usable column — its own or through a link — cannot be an audience, and the editor says so rather than letting you save.

Writing the message

On WhatsApp you must select an approved template. Meta only allows a business to start a conversation with one, and there is no guarantee the 24-hour window is open when the task runs. See templates and quality.

On Telegram you write the message text directly.

Template parameters can be filled three ways:

Column is what makes the message personal — bind a parameter to first_name or amount_due and every recipient gets their own. There is no contact name or agent name token here, because an audience has no single contact behind it.

Columns on a linked table are offered here too, on the same terms as Send to above — so a payment reminder can greet people by the name held on their contact record without copying it onto every payment. In Telegram message text they are written {{contact.first_name}}.

Attaching an image

An audience message can carry one image, sent as a single message with your text as its caption — not a photo followed by a separate bubble. Everyone in the audience gets the same image; it cannot vary per row.

Only images shared with all conversations can be attached. Open the file in Assets, choose Share with all conversations, and give the agent permission to send it. Files belonging to one customer — anything they uploaded in a chat, or an image the agent generated for them — are deliberately not offered: an audience message has no single customer behind it, so there is nothing to check a private file against.

On Telegram you can attach an image to any message. Keep the text under 1,024 characters — past that, the remainder arrives as a second message.

On WhatsApp the image travels in the template's header, so it only works with a template that Meta approved with an Image header. Create one in WhatsApp Manager with header type Image; the Image field appears once you select it, and is then required. A template's layout is fixed when Meta approves it, so an image cannot be added to a text-only template.

Checking who matches

Select Check who matches before saving. It reports how many people will be messaged, lists the first few with their addresses partly hidden, and tells you how many matching rows were skipped — separately for rows with no address and rows not linked to a record in the table being messaged.

The preview stores nothing and sends nothing. Use it — a mistyped filter is invisible until the messages have gone out.

Updating the row after sending

After sending, update lists the columns to write back to once the message has gone out. Add as many as you need — the rows stack the same way filters do.

This matters more than it looks. A recurring task has to change something about the rows it just messaged, or it matches the same people again on the next run.

Each row picks a column and what to write into it. What is on offer depends on the column:

Record that they were reached

Write the send time into a column, so a task filtered on "reminder sent is empty" stops matching that row.

Move a date forward to the next cycle

Move forward by N months sets the column to its own current value plus that many months, instead of the send time. This is the recurring-due-date shape: a subscription renewal, an appointment, an insurance premium.

Say policies carry a next_premium_due_date. One task covers every quarterly policy:

Each run messages whoever is due in a week and rolls their date to the next quarter, so the following quarter is picked up with no further setup. Author one task per frequency — monthly forward by 1, semi-annual by 6, annual by 12 — each filtered to its own frequency value.

Only date columns can be moved forward. Date-and-time and text columns can still be stamped with the send time. If a row's date column is empty or unreadable, that row is still messaged but that column is not written — writing the send time there would silently re-date the record to today. The rest of the row's write-backs still apply.

Multi-step follow-ups

Stacking is what makes a follow-up sequence possible: a column records which step someone is on, the filter reads it to decide who gets which message, and the write-back advances it.

Say contacts carry a follow_up_msg number. Author one task per step:

After step 1 goes out, those contacts stop matching step 1 and start matching step 2, so the next run picks them up with the next message. Someone at 3 matches neither and drops out of the sequence.

Add to it does the same job without naming the next number — follow_up_msg plus 1 reads whatever the row holds and adds one. A row where the column is empty counts as zero, so it becomes 1. Use whichever reads more clearly; the filter still decides the template either way.

What applies to every write-back

A write-back happens only if the agent has update permission on that column, and only after the message has gone out. If one fails, the message is not re-sent — the send is the thing that matters, and a failed write-back is recorded in the logs. Columns are handled independently: a column the agent may not write is skipped while the rest still apply.

Limits

• An audience is capped at 5,000 recipients. Over that, the task sends nothing rather than an arbitrary subset — messaging half a list is worse than messaging none of it.
• If the audience is larger than your workspace's remaining monthly allowance, it also sends nothing. Check interaction counting and your plan's allowance before scheduling a large run. An image doubles what each recipient costs, so it halves how large an audience your remaining allowance covers.
• Messages go out steadily rather than all at once, because WhatsApp and Telegram both pace what a business can send. A large audience takes a while to work through.
• Failed sends are retried a few times with an increasing gap. Someone who has blocked your bot, or whose number is not reachable, is not retried.

Who can be messaged

The channel's allow and deny lists apply to every message an audience sends, exactly as they do to someone messaging in. If a channel is Restricted, only people its allow list covers are messaged. See access control.

On WhatsApp, a customer who has opted out of marketing is skipped for marketing templates, but still receives utility ones. See opting out of marketing messages.

An agent cannot create an audience message for itself. They are made in the dashboard only.

Troubleshooting

Related pages

• Scheduled tasks
• Data tables
• WhatsApp setup
• Telegram setup
• Access control
• Interaction counting