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! 🍕"

A recipient is the receiver for a message from a campaign, and it can be a channel or a user according to the segment type used in the campaign.

All endpoints are only available with server side authentication.

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 campaigns and if it is in use by a campaign, it can't be deleted.

Create a Campaign


Create the message you will be sending to the segment audience. A channel type is specified because a channel with the given type will be created to send the message between message receiver and campaign sender users.

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, and view or delete recipients.

Segment Management


Campaign Management


Recipient Management


Recipients are internally managed by campaign lifecycle. View and delete are supported.



Querying segments, campaigns and recipients support our common operator syntax

Sent and Open Rates


Campaign contains various metadata such as status and its related timestamps, sent_messages, errored_messages, read ratio, etc.

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

Dashboard Support


Dashboard has a separate tab to manage campaigns and supports all the features of campaigns, and is the recommended way of using campaigns.

Future State

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