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 1,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.
2. Create and target different user base Segments like regions, user groups, and more to send Campaigns.
3. Benefit from using message templates, attachments, and custom data to personalize campaign messages to fit their brand.
4. Perform actions such as pausing, resuming, and adding targets without worrying about sending duplicate messages to their user base.

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

1. Create a segment of users or channels to target:

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 consisting of the Segment, message text, description, or any other relevant metadata:

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, update, or resume:

Once a Campaign is live, Stream provides methods for checking the status and monitoring the performance of Campaigns:

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 also listen to webhook events on our Chat API for different events related to Campaigns — making sending push notifications or other in-app engagements a breeze!

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"
}

Starting today, the Campaigns API is available on the Stream Chat API. If you're currently developing an app that might benefit from it, be sure to contact our team. We’d love to hear your feedback as we continue to develop and optimize this new feature. To get started, check out our Campaigns documentation to learn more!