Campaigns

A campaign sends the same message to every contact of a group, wave after wave, at the pace you set. The gateway spreads the messages over your phones, follows each one, and shows live how many left, were delivered or failed.

Everything on this page happens in Campaigns, in the Messages section of the menu.

What campaigns are for

• Announcing a promotion, an opening, a price change to all your customers.
• Reminding a list of people of an appointment or a deadline.
• Informing members of an association, parents of a school, staff of a company.

For one message or a short list typed by hand, use Quick send instead: see Sending messages.

Before you start

• A contact group with the recipients: see Contacts and groups.
• At least one connected phone with SIM cards that can send: see Devices.
• An Operator or Superadmin account. A Read only account sees the campaigns but no button.

Create a campaign

Click New campaign. The Create a campaign window has three steps.

Step 1: Name and recipients

When the campaign is created, the gateway takes the reachable members of the group at that moment:

• contacts who opted out (STOP) are left out;
• a number present twice is only sent once;
• a group with no reachable contact is refused, with an explanation, rather than giving an empty campaign;
• a campaign holds at most 50,000 recipients.

Step 2: Message

Important: a campaign sends the same text to everyone. Template placeholders are resolved once, at creation, without any contact's details: {firstname|Dear customer} becomes "Dear customer" for everyone, and {firstname} without a fallback stays visible as is. Use fallback values, or write the text without placeholders.

Step 3: Pace and scheduling

Leave the pace fields empty to use the gateway defaults. The pace of a campaign is a ceiling: the real speed also depends on your phones, the quota of each SIM and the per-SIM limits of the settings, per minute and minimum interval between two SMS (see SIM cadence).

The Summary at the bottom recalls what will happen. Then:

• Send now creates the campaign and starts it immediately.
• Schedule creates it in Scheduled state; it starts by itself at the chosen time. Until then you can edit it, start it earlier with Start, or cancel it.

If the campaign is created but cannot start (no phone online, for instance), the window closes anyway and a message tells you why: the campaign stays in the list as a Draft, with its Start button. Do not create it a second time.

Follow a campaign

Each row of the list shows the status, a progress bar and the counters:

While it runs, the row also shows the pace, the start date and an estimated end, computed from the pace you set.

The Status filter narrows the list to one status:

The status is always driven by the gateway: it never changes by hand, only through the buttons below.

Actions

The main button of a row depends on its status (Start, Pause, Resume or Relaunch). The ... menu at the end of the row lists every action, and stays in view even on a narrow screen where the table scrolls sideways. An action you may expect but that the status does not allow yet (deleting a running campaign, for instance) stays in the menu, greyed out, with the reason written under it.

To send a completed campaign again to the whole group, Duplicate it.

Relaunch a cancelled campaign

Relaunch picks a cancelled campaign up again, for the recipients who did not receive the message: those it had not reached yet, and those whose message was withdrawn from the queue when you cancelled. The window tells you how many they are. Recipients who already received the message are never sent it a second time.

The campaign keeps its message, its short links, its pace and its statistics: the counters continue from where they were, and the Cancelled counter goes back to zero as the recipients return to Pending. The night and Sunday pauses apply as usual.

Once a relaunched campaign has started, its text and pace stay frozen, even if you scheduled the relaunch: only Rename remains. Recipients whose message failed are not sent again by a relaunch; to reach them, duplicate the campaign into a new one.

Relaunch is greyed out when nobody is left to send to: every recipient already received the message or failed.

Delete a campaign

Deleting removes the campaign, its list of recipients and its statistics, for good. A confirmation window says so before anything happens.

• Messages already sent stay in the message history and the conversations: they are your record of what left.
• Its short links keep working, since recipients may still open them days later. They are simply no longer attached to a campaign in Short links.
• A Running or Paused campaign cannot be deleted: cancel it first, then delete it.
• Right after a cancellation, a message that was already on a phone may still be on its way. Delete stays greyed out ("Some messages are still on their way") until it has settled, which takes at most a few minutes.

Night and Sunday pauses

In Settings > Sending, the Night pause for campaigns and Pause campaigns on Sunday hold campaigns only. While a pause is active:

• a running campaign stays Running but releases nothing, then continues on its own when the pause ends. You never have to resume it by hand;
• campaign messages already in the queue wait too: a wave released at 19:59 does not leave at 22:00;
• everything else leaves at any hour: quick send, API calls, conversation replies, automatic replies.

The pauses are read in the platform time zone. See Settings.

What else affects a campaign

With the API

With an API key, reading needs the read scope and every change needs the admin scope. See API keys.

Without scheduledAt, the campaign is created as a draft and waits for /start; with a future scheduledAt, it is scheduled. A date in the past is refused (SCHEDULED_AT_IN_PAST). The campaign.completed event can notify your tools: see Webhooks.

A relaunch keeps the same campaign identifier. Relaunching a campaign that is not cancelled returns 403 VALIDATION_ERROR; relaunching one with nobody left returns 422 VALIDATION_ERROR. Deleting a running or paused campaign, or a cancelled one with a message still on its way, returns 403 CAMPAIGN_NOT_DELETABLE. Editing anything else than the name of a campaign that has started returns 403 CAMPAIGN_NOT_EDITABLE.

Troubleshooting