Campaign API

The Campaign API makes it easy to send a message or send an announcement to a large group of users and/or channels. You can personalize the message using templates. For small campaigns of less than 1000 users, you can directly send the campaign. If you need to maintain larger segments of users or channels that's also supported. The potential applications of this feature are virtually limitless, yet here are some specific examples:

• Marketing Campaigns: Send promotional messages or announcements to a targeted audience.

• Product Updates: Inform users about new features, bug fixes, or enhancements to your product.

• Event Reminders: Send reminders about upcoming events, webinars, or conferences to registered attendees.

• Customer Surveys: Engage with your user base by sending out surveys or feedback forms to gather feedback.

• Announcements: Broadcast important company news, policy changes, or updates to stakeholders.

• Campaign Scheduling: Plan and schedule campaigns in advance to ensure timely delivery and maximize impact

Under the hood, campaigns send messages to the specified target audience and do so on behalf of a designated user (sender). If there are no existing channels to deliver messages to the target users, campaigns can automatically create them. Additionally, campaigns might generate more events for creating channels and sending new messages. These events can be sent as In-App messages and/or Push Notifications to the end users, and as Webhook calls to your backend server.

The Campaigns API is designed for backend-to-backend interactions and is not intended for direct use by client-side applications.

By default we have rate limits in place to ensure that campaigns don't cause stability issues. The throughput supports sending campaigns with tens of millions of messages. Be sure to reach out to support to collaborate with our team and raise your limits.

Here's a basic example of how to send a campaign.

The campaign exposes methods to create, get, update, start, stop delete and query campaigns.

Here are the supported options for creating a campaign:

Note that campaigns can only be sent once. If you want to repeate the same campaign you have to create a new campaign object with the same template and segment ids.

The message template uses Django/Jinja style variables. So you can use {{ myvariable }} to customize the message. The following fields are available:

So for example you could use a template like: "Hi {{ receiver.name }} welcome to the community". Messages sent by the campaign API will automatically contain the campaign_id custom field and will have type set to regular.

Here's an example channel template. It enables the campaign API to find the right channel for a recipient and sender.

You can query campaigns based on extensive set of filters and sort options

Following code sample provides various examples of filters:

Segments enable you to target large groups of users. You can either specify a large list of user ids, channel ids, or filters that search the user database. There is no limit on how many users you can have in a segment.

You can create, update or delete segments. You can also add users to the segment. The above approach specified a filter to query the users. Alternatively you can also manually provide a list of user ids.

The example below shows how to create a segment with all users:

User segment supports following options as part of data:

You can also create segments of channels to target. If you target a channel the “receiver” message template variable will not be available.

The example below shows how to create a segment which targets all the channels where sender is member of

Channel segment supports following options as part of the data:

For getting a specified segment you may use the following code snippet:

The received response will contain the segment data:

Please, take into account that:

• Parameters filter, all_users and all_sender_channels are mutually exclusive.

• The size is calculated asynchronously when either filter or all_users is set.

• The size is calculated in place if you add targets manually using segment.addTargets(...) function

The example below shows you how to create a segment and send a campaign to it

Campaign status have following possible values:

• draft - Campaign has been created but not scheduled

• scheduled - Campaign has been scheduled

• stopped - Campaign has been stopped manually or using stop_at option

• completed - Campaign has succesfully completed

• in_progress - Campaign is running at the moment

Sending campaigns is fast but not realtime. It can take several minutes for your campaign to complete sending. A campaign with 60,000 users typically takes ~1 minute to send.

The campaign API returns stats when you call campaign.get.

Your app will often want to know when a campaign API starts or stops. Your server hooks will receive an event when the campaign starts and another when the campaign is completed.

Both events include the full campaign object with its status and stats.

client.querySegments allows you to paginate over a large segment with up to 10,000 results per page.

The list of users is sorted by ID ASC. This means that you can easily compare it to your internal list of users in this segment, and call segment.addTargets/addTargets as needed.

Page updated Feb 20th 5:42