This feature is in beta and must be enabled on your app before you can use it. Please contact support if you are interested in trying this out.

The Campaign API lets you send a personalized message to a segment of users or channels. Using this feature, you can contact users while they are online using chat.

There are unlimited possibilities for how you could use this, but here are some common examples:

  • News or Upcoming Events

  • Deals and Promotions

  • New Feature Alerts

  • Product Recommendations

Core Concepts


A segment is the target audience for your campaign. You can query for users and channels using the same queries which are supported today to build the segment. 

A campaign is the message, and optionally links or attachments, which will be sent to the segment of users. Campaign messages can be personalized for each user, for example: “Hey {{}}, this is {{}} with a present for you! Use the promo code XHNV8T during checkout on your next order and enjoy the best pizza in town! 🍕"

Both campaigns and segments are managed server-side only.

Steps to Send a Campaign


Create a Segment


First create a collection of users or channels to send a message. These can be reused for any future campaign too.

Create a Campaign


Create the message you will be sending to the segment audience

There are three supported templating namespaces:


  • Targets fields of the recipient user. It will only work for 1:1 conversations (channels with 2 participants where one of them is the sender), or it will be skipped otherwise.

  • It supports the user’s id, role, and language fields, plus any custom data attached to the user object. Nested properties are available with a “flat”, dot-separated notation.


  • Targets fields of the sender user. It has the same data access patterns as the user.* variables.


  • Targets fields of the destination channel. It supports the id, type, and CID properties of the channel.

Test Campaign


You can optionally test the campaign before sending to real users

Schedule Delivery


Once you are comfortable with the campaign message and audience segment, schedule the campaign to be delivered at a certain date/time.

Monitor Campaign Status


Because things don't always go as planned, you are able to monitor the status of a campaign to confirm it was successful, and cancel if needed.

Maintaining Segments and Campaigns


You can also view, edit or delete segments and campaigns

Segment Management


Campaign Management


For API request and response details, see the REST docs.

Future State...

  • Right now, the Campaign API is only available to a limited number of beta-testers. In the future, we will open this API to all Stream Chat users.

  • Also planning to expand server side SDK support

  • The only way to run a campaign right now is by using APIs. In the future, we will support it through a GUI for Campaigns through the Dashboard.

  • We would love to hear from you on how to improve this feature... please leave your feedback below.