Introducing Stream’s Campaigns API

We at Stream are thrilled to announce the launch of our new Campaigns API! Sending messages to a large group of users or channels and personalizing those messages with rich templating, attachments, and custom data is now easier for developers and businesses than ever before.

For Campaigns with under 10,000 users, our API enables you to send messages directly to a list of users without creating a Segment. For larger groups or more targeted campaigns, Segments can be used to create different cohorts of users based on user-defined criteria.

From a technical perspective, apps utilizing Stream’s Campaigns API can:

1. Quickly and easily send messages to small groups using a defined user list of up to 10,000 users.
2. Create and target different user base Segments like regions, user groups, and more — or target Segments of existing channels directly.
3. Benefit from using message templates, attachments, polls, and custom data to personalize campaign messages to fit their brand.
4. Perform actions such as scheduling, pausing, resuming, and stopping campaigns, with built-in auto-stop support so campaigns can wind down at a specified time without manual intervention.
5. Control whether the sender appears in new channels, whether hidden channels are surfaced to recipients, and whether push notifications or webhooks fire for campaign-generated events.

For example, a developer or app leveraging our Campaigns API can expect the following workflow:

1. Create a Segment to Target:

Segments support filter-based targeting, manual user or channel lists, or handy shorthands like targeting all users in the app or all channels where the sender is a member.

1
2
3
4
5
6
7
const data = {
  filter: {
    team: "commonteam",
  },
};
const segment = client.segment("user" | "channel", data);
await segment.create();

2. Create a Campaign Object

Create a Campaign object consisting of the Segment, message template, and any relevant configuration — including whether channels should be created automatically for recipients who don't have one yet, and how the sender should appear (or not appear) across those channels.

1
2
3
4
5
6
7
8
9
10
const campaign = client.campaign({
  segment_ids: [segment1.id, segment2.id],
  sender_id: 'user-id-of-sender', // mandatory
  name: 'Campaign name (optional)',
  description: 'Optional description',
  message_template: {
      text: 'Hi {{ receiver.name }} I\'m {{ sender.name }}!',
  }
})
await campaign.start(scheduled_at) // omit scheduled_at to start immediately

Note: In the example above, we are sending the Campaign immediately. However, a user can schedule the message to be sent later.

3. Send, Monitor, & Manage

Once a Campaign is live, Stream provides methods for checking status, updating the campaign, and stopping it. Campaigns progress through five clear statuses: draft, scheduled, in_progress, stopped, and completed.

When you check on a running or completed campaign, the API returns stats including how many messages were sent, how many channels were created, overall progress, and — new since launch — how many users actually read the message.

1
2
3
4
5
await campaign.get();
await campaign.update({ ... });
await campaign.start(scheduledAt);
await campaign.stop();
await campaign.delete();

When campaign.get is called, the API returns a JSON response containing information on the performance and success rate of the messages.

1
2
3
4
5
6
7
8
{
stats: {
   "started_at":  "2024-23-02 00:00:00",
   "completed_at": "2024-23-02 01:00:00"
   "messages_sent": 1000
   "channels_created": 10
 }
}

Finally, developers can listen to webhook events on our Chat API for campaign lifecycle milestones. When a campaign begins sending, your server receives a campaign.started event. When it finishes, a campaign.completed event follows — both including the full campaign object with current status and stats, making it straightforward to trigger push notifications or other in-app engagements off the back of campaign activity.

1
2
3
4
5
6
7
8
9
{
    "type": "campaign.updated", 
    "campaign": {
        "status": "scheduled|running|paused|finished"
        "...": ...
        "stats": {}
    },
    "created_at": "2024-23-02 00:00:00"
}

The Campaigns API is available on the Stream Chat API. All paid plans include message capacity equal to three times your monthly active user volume, so a 100,000 MAU plan comes with 300,000 campaign messages per month. If you need higher throughput, reach out to our team. To get started, check out our Campaigns documentation to learn more!