docs
/
AI skills

Broadcast audience from a filter

Turn "everyone who…" into an audience a broadcast works out again at every send — a smart customer group for rules on contacts, or a dynamic list for rules on any collection (form signups, orders, carts) — previewed and counted first, then a draft addressed to it. A person sends.

A filter audience is worked out again every time the broadcast sends. People join and leave it as their records change. Nobody is put in by hand.

There are two kinds. Pick by where the people are:

The people are…UseSaved asThe broadcast lists it as
contacts, picked by fields on the contact (city, tag, group, signup date, status)a smart customer groupcustomer_group with groupType dynamic<group sk>
rows in any other collection: form answers, orders, carts, signups, or a join of severala dynamic listdataviz_item with type queryquery:<item sk>

A smart group is also a real customer group: it shows on the Customer Groups tab with its count, and other broadcasts can reuse it. A dynamic list exists only for broadcasts.

A broadcast sends real messages to real people. This skill stops at a draft.

Ask first

  • Who, in their words. "Customers in Austin who bought in the last 90 days." Turn it into rules (below) and read them back in plain words before saving.
  • Which channel? Email reaches people with an address; SMS, WhatsApp and voice reach people with a phone number. The same filter gives different counts.
  • For a dynamic list on a repeating broadcast: should each record be sent to once (a cart is emailed once, ever), or should everyone it finds get every run (a weekly newsletter)?
  • The message and the sender, as for any draft (email, SMS).

Rules

Both kinds use the same rule engine. A rule is { "field": "<field>", "operator": "<operator>", "value": "<value>" }.

  • field is a field of the record, written without data. (address.city, tags, email). sk, createdate, modifydate, author and state are the record's own fields and are written as they are.
  • Text matches ignore case and spaces at the ends. A list field (tags, groups) matches when any of its values does. Dates compare as dates.
operatorMeansvalue
equals / not_equalsis / is notone value
in / not_inis any of / none ofvalues separated by commas
contains / not_containshas the text in it / doesn'ttext
starts_with / ends_withbegins / ends withtext
gt gte lt lte> ≥ < ≤a number or a date
before / afterearlier / later thana date
in_last_days / not_in_last_dayswithin the last N days of the send / notN
is_empty / is_not_emptyhas no value / has onenone

Rules are joined by all (every rule holds) or any (at least one holds). An unknown operator matches no one.

Steps

1. Try the rules before saving

Preview, so the person sees real names before anything is saved.

  • Smart group: call_appengine POST /crm/customer-groups/match with { "group": { "groupType": "dynamic", "addRules": [<rules>], "addRulesMatch": "all" } }. The answer is the contacts it holds now (total, a page of data) and the query it ran.
  • Dynamic list: POST /broadcast/audience/query-preview with { "collection": "<collection name>", "rules": [<rules>], "rulesMatch": "all", "channel": "email" }. The answer has the first rows, count (rows) and reach (people the channel can reach after unsubscribes are taken out).

If the count is far from what the person expects, show a few names and fix the rules. Don't save a list nobody checked.

Hands on: the rules and how many they reach. Check: read the rules back in words ("contacts whose city is Austin and whose last order is in the last 90 days: 212 people, 198 with an email").

2. Customers & Benefits (or Broadcast): save it

Smart group. Create a customer_group with create_record:

FieldValue
namee.g. "Austin buyers, last 90 days"
descriptionthe rules in words
groupTypedynamic
addRulesthe rules
addRulesMatchall or any

Nobody can be added to or taken out of a smart group by hand. POST /crm/customer-groups/members refuses it, because its rules decide.

Dynamic list. Create a dataviz_item with create_record. This is what the composer's Recipients → Dynamic → Save and use this list writes:

FieldValue
typequery
titlee.g. "Newsletter signups"
namelowercase letters, digits and -, 3–80 long, unique, e.g. newsletter-signups-k3f9qa
content.collectionthe collection the rows come from
content.modesimple
content.rules / content.rulesMatchthe rules, and all or any
content.mongoQuery""

Hands on: the group's sk, or the item's sk. Check: POST /broadcast/audience/count with { "lists": ["<group sk>"] } or { "lists": ["query:<item sk>"] }, and "channel". It matches the preview. Open a smart group at /customers-benefits?view=groups&groupId=<sk>.

3. Broadcast: the draft addressed to it

Create the email_broadcast draft as in Email campaign draft to a customer group or SMS broadcast to a group, with these audience fields:

AudiencerecipientMethodselectedListsAlso
smart grouplists["<group sk>"]it can sit beside other groups; a person on two lists gets one message
dynamic listdynamic["query:<item sk>"]one dynamic list, on its own (the composer keeps one and drops other lists); resendEachRun (below)

resendEachRun (dynamic lists only). Off (the default): each row the list finds is sent to once by this broadcast, across all its runs, so a daily run doesn't email the same cart every day. On: everyone it finds gets every run, as a newsletter should.

Never set status to pending or scheduled, never add a schedule, and never call POST /broadcast/<id>/send.

Hands on: the broadcast's sk. Check: POST /broadcast/audience/total with { "lists": [<the list ids>], "channel": "<channel>" } gives the count from step 2. Open the draft (/broadcast?openId=<sk>). On Recipients, a smart group is ticked under Lists, or Dynamic shows the saved list with its preview.

Advanced: a written query

When rules can't say it (a join, "carts not changed in 3 days with the owner's email"), a dynamic list can hold a Data Viz pipeline instead: content.mode advanced, content.mongoQuery the pipeline as JSON text, content.rules []. Preview it first with POST /broadcast/audience/query-preview and { "collection": "<name>", "pipeline": "<JSON text>", "channel": "email" }.

  • It must be a JSON array of stages. $lookup other collections by their name.
  • Each row is one person: email (or emailAddress), phone (or phoneNumber), and name or firstName / lastName, at the top of the row or under data.
  • Every field of the row can go in the message: {{data.<field>}} or {{data.<collection>.<field>}}.
  • It can't use Data Viz's {{startDate}} / {{endDate}}: a send has no date range. Use "$$NOW" for time rules. A query that fails stops the send with its reason.
  • Keep _id or sk on rows when "once per record" matters: it is what resendEachRun off counts.

A smart group can be written the same way (queryMode advanced, query a filter or pipeline on contacts, as JSON text).

Follow-up to people who didn't open uses one of these on the delivery log.

Stop

Sending is the person's decision. Show the audience in words, the count on the channel, the message and the sender, and say the audience is worked out again at the moment it sends, so the number can change. They press Settings & Send → Send Now, or add a time under Settings & Send → Schedule → Add schedule.

When it's done

Tell the person:

  • the audience in words, and whether it is a smart group or a dynamic list;
  • how many it reaches now, on the channel;
  • the draft's name, and that nothing has been sent.

What it can't do yet

  • No count is frozen. A filter audience is read at send time. To send to exactly today's people, save them in a static group.
  • A dynamic list has no screen of its own outside the composer (Recipients → Dynamic → Open a saved list).
  • The older recipientSegment filter on a broadcast (with recipientType) only does "equals" and "contains" and isn't shown in the composer. Don't use it; use a smart group or a dynamic list.

Don'ts

  • Don't use all-contacts or all-leads as a shortcut for "everyone who…". They are everyone.
  • Don't save rules the person hasn't seen in words with a count.
  • Don't hand-add people to a smart group, or switch a static group the person built by hand to dynamic. Its members would be replaced by whatever the rules match.