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.

All paid plans include 3 times the procured MAU volume in message capacity. Ex: if you have a 100,000 MAU plan you can send 300,000 campaign messages each month. If you need to send more messages than this limit reach out to our sales team

Sending a Campaign

Copied!

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

You can send the campaign immediately or schedule it to start at a later time. You can also stop the campaign at any time.

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

Creating a Campaign

Copied!

Here are the supported options for creating a campaign:

nametypedescriptiondefaultoptional
idstringSpecify an ID for your campaign-
namestringThe name of the campaign-
descriptionstringThe description for the campaign-
segment_idsstringA list of segments to target. Max 25. Use either segment_ids or user_ids to target your campaign. The campaign will automatically remove duplicates if users are present in more than 1 segment. -
user_idsstringA list of user ids to target. Max 1000 users, for bigger campaigns create a user segment first. Use either user_ids or segment_ids to target your campaign.-
sender_idstringThe user id of the user that's sending the campaign. -
message_templatestringA message template-
create_channelsbooleanIf true then channels will be created if they don't exist yetfalse
channel_templatestringThe template to use when creating a channel-
skip_pushbooleanDo not send push notifications for events generated by this campaign, such as message.new or channel.createdfalse
skip_webhookbooleanDo not call webhooks for events generated by this campaign, such as message.new or channel.createdfalse

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.

Message Template

Copied!

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

VarIABLE

Description

Sender

User object that's sending this campaign

Receiver

The person receiving the message. This is only available in 1-1 channels, and not when sending to a group

Channel

The channel the message is being sent to

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.

Channel Template

Copied!

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

Querying Campaigns

Copied!

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

Following code sample provides various examples of filters:

Segments for Campaigns

Copied!

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.

User Segments

Copied!

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:

nametypedescriptiondefaultoptional
namestringName for the segment-
descriptionstringDescription of the segment-
filterjsonFilter criteria for target users of this segmentnull
all_usersbooleanIf true, segment will target all the users of the appfalse

Channel Segments

Copied!

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:

nametypedescriptiondefaultoptional
namestringName of the segment-
descriptionstringDescription for the segment-
filterjsonFilter criteria for target channels of this segmentnull
all_sender_channelsbooleanIf true, segment will target all the channels where sender is member offalse

Getting Segment

Copied!

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

The received response will contain the segment data:

nametypedescriptiondefaultoptional
idstringID of the segment-
typestringType of the segment ("user" or "channel")-
namestringName of the segment""
descriptionstringDescription of the segment""
filter

object

Filter criteria for target users or channels of this segmentnil
all_usersbooleanIf true, then segment targets all the users of the appfalse
all_sender_channelsbooleanIf true, then segment targets all the channels where sender is member offalse
sizeintegerNumber of the targets for this segment0
created_atstringDate when the segment was created-
updated_atstringDate when the segment was update-
deleted_atstringDate when the segment was deleted-

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 size won't be calculated at all if all_sender_channels is set to true. If you want the size to be calculated for the channel segment types, please provide the filter instead.

Sending a Campaign to Segments - Full example

Copied!

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

Create a segment for user’s in the USA

Copied!

Message the above segment

Copied!

Check the status of the campaign

Copied!

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.

Campaign Stats

Copied!

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

Webhooks

Copied!

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.

Updating a large Segment

Copied!

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