Skip to main content

Audiences and message campaigns

An audience is a company-wide list of people. A message campaign sends one message, or an ordered chain of messages, to one or more audiences over SMS/MMS, WhatsApp, Telegram, Messenger, Instagram or e-mail. Both are under Campaigns in the console, next to the voice campaigns, and both are available through the API (/audiences, /contact-optouts, /message-campaigns).

note

This page describes how the product behaves and what each channel's provider requires. It is not legal advice. Which consent you need depends on your country and your business; ask your counsel.

Audiences​

A person in an audience has a name and any of: a phone number (stored as E.164, for example +15550100100), an e-mail address, a Telegram chat id, a WhatsApp id (the phone's digits when empty), Messenger and Instagram page-scoped ids, a language, a time zone, a country and custom fields you can use in message templates ({plan}). Each person also carries the consent per channel: opted in or not, when, and where it was given.

  • Nothing implies consent. A person is opted in to a channel only when you record it, with the source ("web form 2026-10", "shop checkout").
  • A phone, e-mail address or channel id appears once per audience.
  • Lists of 100,000 people and more are searched and paged on the server; consent can be recorded for many people at once.
  • The same person in two audiences is messaged once by a campaign that targets both (the phone identifies them, else the e-mail address, else a channel id).

Getting people in​

FromHow
A fileCSV or Excel (.xlsx, .xls) with the import wizard (below)
The contacts directoryImport from contacts: the company phonebook or one user's contacts that have a usable number or address. Contacts carry no consent.
The inboxImport from inbox: the people who wrote on Telegram, Messenger, Instagram and WhatsApp. A WhatsApp number becomes the person's phone. A Telegram, Messenger or Instagram id is a separate person until you tie the conversation to a person (the inbox conversation can be linked to an entry). Writing in is not consent.
The APIPOST /audiences/{id}/entries for one person, POST /audiences/{id}/import for a small CSV

The import wizard​

  1. Upload a CSV or Excel file. The file is streamed to the server, never held in memory. The limit is set by the operator (default 512 MB, about a million rows and more); a bigger file is refused with MPBX-AUDIENCE-IMPORT-TOO-LARGE, and a company over its storage quota with MPBX-STORAGE-QUOTA-EXCEEDED. Nothing is stored in either case and nothing is ever deleted to make room.
  2. Preview. The wizard detects the encoding (UTF-8, UTF-8 with BOM, Windows-1252) and the delimiter (comma, semicolon, tab), lists the sheets of a workbook so you can pick one, shows the header and the first rows, and proposes the column mapping. If you imported a file with the same header before, the mapping you used then is proposed.
  3. Map the columns to a person's fields, to custom fields (field:plan), or to a consent column (consent:sms, yes or no). You can also state that everybody in the file opted in to some channels; that needs the source, which is stored with the consent.
  4. Import. A background job reads the file in batches of 2,000 rows with live progress (rows read, stored, refused, repeated), also published on the events WebSocket as audience.import_progress. You can cancel it; people already stored stay. The job survives a restart of the server and carries on where it was. Rows that repeat a person already in the list are skipped.
  5. Report. Refused rows (invalid phone or e-mail, a national number with no country chosen, no way to reach the person) are listed with the reason and can be downloaded as a CSV together with the row as it was in the file.

Templates. Download an empty CSV or XLSX from the wizard (or GET /audiences/import-template) with a header for every field, a consent column per channel, field: columns for the custom fields you name and two example rows. The headers (and, in the workbook, a sheet of notes) are in your language; the import recognises them. Delete the example rows before importing.

Opt-outs​

One do-not-contact store serves every channel. An entry is a channel (sms, whatsapp, telegram, messenger, instagram, email, voice, or all) and a number, address or id.

It is filled byNotes
SMS STOP, UNSUBSCRIBE, CANCEL, END, QUIT (and the localised words)handled by the SMS core; mirrored here
STOP, UNSUBSCRIBE and the localised words as a whole message on WhatsApp, Telegram, Messenger, InstagramSTART takes the person back
The unsubscribe link of campaign messagesone click, in the browser's language, opts the person out of the channel it came on
"Press 9" (the opt-out key) in outbound AI calls and in the do-not-call listexisting do-not-call entries were moved into the store; the do-not-call list keeps working
AdministratorsOpt-outs page or the API, audited

Removing an entry is audited and should happen only when the person asked to be contacted again. Campaigns check the store before every message, also in campaigns already running.

Message campaigns​

A campaign has:

  • Audiences: one or many; people are de-duplicated.
  • Steps: a channel and its content each. With more than one step, the later steps are fallbacks: for example a WhatsApp template first, then an SMS if the person is not on WhatsApp or the message was not delivered within 30 minutes.
  • Purpose: marketing (consent per channel required) or transactional (an appointment reminder, a delivery update; consent is not required by the product, opt-outs still apply).
  • Send window in the person's time zone (the one on the entry, else the campaign's), with days of the week; rate per minute; retries of temporary failures.
  • Templates with {field} and {field|default} substitution, a text per language chosen by the person's language, an SMS segment counter (GSM 7-bit 160/153 characters per part, UCS-2 70/67), an e-mail subject and HTML with the mandatory {unsubscribe_url} link, and for WhatsApp the approved template with the values of its placeholders (picked from your WhatsApp Business account).
  • Lifecycle: draft, scheduled, running, paused, stopped (final), completed. Start, schedule, pause, resume and stop from the page.

Before you start, the campaign shows how many people it can reach per channel (people with an address, the consent the purpose needs and no opt-out) and, if you configured a price per SMS segment, an upper bound of the SMS cost. While it runs you see sent, delivered, read, replied, failed, skipped (and why: no address, no consent, window closed, no template), opted out and the actual cost, live; the people can be listed and exported as CSV.

A reply lands in the shared inbox like any other message and is marked on the person's row with a link to the conversation. The person's history across campaigns (last contacted, outcome, count) is on the person.

What each channel allows​

The scheduler applies these rules to every person. Someone a channel may not reach is skipped, counted and, with a fallback, handed to the next step. The rules below are the providers' own; they change, so check the sources.

ChannelRule enforced
WhatsAppOutside the 24-hour customer service window only an approved template can be sent, so a marketing step needs one. Inside the window (the person wrote in the last 24 hours) free text goes out. Marketing templates need the person's opt-in, which is the consent you record. Delivered and read receipts arrive on the channel's webhook. Template fundamentals
TelegramA bot can message only people who started it, so only people with a chat id (people who wrote to the bot) are reachable. The scheduler stays under about 25 messages per second for the bot (Telegram allows about 30 per second overall, about one per second per chat and 20 per minute per group). Bots FAQ
Messenger and InstagramFree text only inside the 24-hour standard messaging window. Message tags are for approved non-promotional updates and are never used for campaigns; promotional messages outside the window need Meta's own products (Sponsored Messages, one-time notifications), which are not offered here. Delivery receipts name the message; a read receipt covers everything sent up to its watermark (Instagram names the message seen). Messenger Platform policy
SMS and MMSConsent for marketing, opt-out by STOP honoured automatically, the send window in the recipient's time zone, per-segment cost counted. Carrier and country rules (sender registration, quiet hours) remain yours: see the SMS compliance guide.
E-mailConsent for marketing and the unsubscribe link in every message (added if a template forgot it). Messages carry the link in the body and the one-click List-Unsubscribe and List-Unsubscribe-Post headers (RFC 8058), which mailbox providers show as an unsubscribe button (SMTP, Amazon SES, SendGrid and Mailgun).
Apple Messages for Business, Google Business MessagesNot offered: they answer people who write first and have no outbound campaigns.

Voice campaigns on audiences​

Dialer campaigns (agents or blaster) and outbound AI campaigns call audiences too: attach one or many lists to the campaign (PUT /campaigns/{id}/lists, PUT /ai/outbound/campaigns/{id}/lists) and every person with a phone number becomes a contact (or job) of the campaign, unless the number is on the do-not-contact store for voice or for all channels. POST .../lists/sync adds the people who joined the lists since. The campaign keeps its own queue of contacts (attempts, next try, call state); contacts that existed before, and contacts added directly, were moved into an automatically created list per campaign ("Calls: ...", "AI calls: ..."), so their attempts now belong to a person.

  • Press 9. The opt-out key of a dialer or AI call writes the unified store; an entry added there for voice is honoured by both kinds of campaign, and removing it removes it everywhere.
  • History. Every person shows the campaigns that contacted them: messages, dialer calls and AI calls, with the outcome and attempts, and the last contact and count are kept on the person.

Test mode​

Before a real run, send one test call or one test message to a test recipient. Testing is on the campaign's page and in its editor (Test mode), for dialer and blaster campaigns, and, through the API, for outbound AI campaigns and message campaigns.

  • Test recipient. A phone number in international format (test calls, SMS, WhatsApp), an e-mail address, and a Telegram chat id, Messenger id or Instagram id (pick the ids from your inbox contacts). Set a company default under Campaigns, Test recipient of the company (settings:write); a campaign can have its own test recipient, field by field over the default (empty fields use the default).
  • Test call (voice). Places one real call to the test number with exactly the campaign's configuration: the message (spoken text or recording), answering-machine detection and voicemail drop, the agent and opt-out keys, the caller ID, and the extension's dial plan with its outbound rules and toll-fraud guard. It counts against the licence's simultaneous calls like any trunk call. A call to an agent queue (power, preview, predictive) connects you to a free agent, exactly as a real call would. The page shows the call live (ringing, playing the message, waiting for a key) and its outcome. Pressing the opt-out key during a test reports opted out but does not put your number on the do-not-contact list.
  • Send test (messages). Renders every step for a sample person (your name field reads "Test Recipient"; fields the test person does not have show as [field]) and sends one message per channel you tick, under the channel rules: WhatsApp outside the 24-hour window goes as the approved template, Messenger and Instagram only inside their window (otherwise the row says The 24 hour reply window is closed), a channel that is not connected or a step you did not write is skipped with the reason. E-mail subjects start with [Test] and carry a sample unsubscribe link. The page shows sent, delivered and read as the receipts arrive.
  • When. A campaign that is a draft, scheduled or paused can be tested. A running, stopped or completed campaign cannot (pause it first). Outbound AI campaigns have no run state and can always be tested.
  • Safety. A test goes only to the stored test recipient: the address is never taken from the request or from an audience, and the audience is not read or written. Test attempts are kept in their own log, so they are in no campaign statistic, no person's contact history and no estimate or SMS cost total. The do-not-contact store applies: a test recipient on it (for that channel or for all) is refused with a clear message. A campaign takes at most 10 test attempts per hour. Every test and every change of a test recipient is in the audit log.

Large files: server and proxy settings​

The server reads two settings from the [uploads] section of its configuration:

[uploads]
max_import_bytes = 536870912 # the largest import file (default 512 MB)
import_timeout_secs = 3600 # how long one upload may take (default 1 hour)

Keep the proxy's body limit small for the whole site and raise it for the import upload path only (POST /api/v1/audiences/{id}/imports):

  • Caddy (the installer's front): the shipped Caddyfile has a block for that path with request_body { max_size 1GB } and one-hour read and write timeouts.
  • ingress-nginx (Kubernetes): a second Ingress for the same host, /api/v1/audiences/[0-9a-fA-F-]+/imports, with proxy-body-size: 1g, proxy-request-buffering: "off" and one-hour timeouts (deploy/k8s/components/ingress/ingress.yaml).
  • Another proxy: allow a body of at least max_import_bytes on that path, do not buffer the request to memory, and allow an hour of idle read and write time.

Working with the lists​

The campaign hub, the audience list and the opt-out lists work like the Users list: a search box that filters as you type (the hub also has Kind and Status filters, the opt-out list a Channel filter), and the ... menu at the end of a row: Start, Pause, Resume, Stop and Live view on a campaign; Edit and Delete on an audience; Delete on an opt-out. Links to audiences, opt-outs and the test settings are under Related at the top of the campaign hub. Below 640 pixels wide the table turns into cards with no sideways scrolling. A list that cannot be loaded shows the reason and Try again.