Campaign API

const segmentId = '<segment-id>'; // segment_id is optional
// Create a dynamic user segment based on the filter provided.
// e.g., following segment will include all users created after 2020-01-01
const segment = client.segment('user', segmentId, {
  name: 'New App Users Segment (optional)',
  filter: {
    created_at: {
      $gte: '2020-01-01T00:00:00Z',
    }
  }
})
await segment.create();

const campaign_id = '<campaign-id>'; // campaign_id is optional
const campaign = client.campaign(campaign_id, {
  // Users targeted by following segment will receive the message
  segment_ids: [segmentId],
  // Alternatively, instead of segment_ids, you can also provide user_ids to send the message to specific users
  // user_ids: ['<user-id-1>', '<user-id-2>'],
  sender_id: '<user-id-of-sender>', // Mandatory
  // Optional, specifies whether to 'exclude' or 'include' the sender from the channel. Defaults to null.
  sender_mode: 'exclude',
  // Optional, controls the visibility of the new channels for the sender ('hidden' or 'archived'). Defaults to null
  sender_visibility: 'hidden',
  name: 'Campaign name', // Optional
  description: 'Campaign Description', // Optional
  message_template: {
    text: 'Hello {{receiver.name}}!', // Mandatory, message text template
    attachments: [], // Optional, message attachments
    poll_id: 'poll-id', // Optional, send a poll with message
    custom: { promotional: true }, // Optional, custom fields will be added to message object received by the receiver.
  },
  show_channels: true, // Optional, show hidden channels for receiver
  create_channels: true, // Optional, create channel between sender and receiver if not already present
  // channel_template is required if create_channels is true
  channel_template: {
    // Mandatory, channel type
    type: 'messaging',
    // Optional, template for channel id for channel creation
    // if not provided, channel id will be generated on server side
    id: '{{receiver.id}}-{{sender.id}}',
    // Optional, custom fields will be added to channel object
    custom: { promotional: true },
    // Optional, if provided (and multi tenancy is enabled), you can limit accessibility to the channel only to a team
    team: 'kansas-city-chiefs',
    // Optional, if provided following members will be added to each of the newly created channel
    // if not provided, only sender and receiver will be added to the channel
    // You can use this to add e.g., moderator or admin to each newly created channel
    members: ['user-id-1', 'user-id-2'],
    // Alternatively, you can use members_template to specify channel roles and custom data for members.
    // members and members_template cannot be used together.
    // members_template: [
    //   {
    //     user_id: 'user-id-1',
    //     channel_role: 'channel_moderator', // Optional
    //     custom: { key1: 'value1' }, // Optional
    //   },
    //   {
    //     user_id: 'user-id-2',
    //     channel_role: 'channel_moderator', // Optional
    //   },
    // ]
  }
})

await campaign.create();

// Start sending messages to targeted users
await campaign.start();

// Alternatively you can also schedule the campaign to start at a later time and stop at a specific time
await campaign.start({
  scheduledFor: new Date(Date.now() + 48 * 60 * 60 * 1000).toISOString()
  stopAt: new Date(Date.now() + 72 * 60 * 60 * 1000).toISOString()
});

# Note: Segment and campaign creation are not yet available in the getstream SDK.
# The following operations are available:

# Query campaigns
response = client.chat.query_campaigns()

# Get a specific campaign
response = client.chat.get_campaign(id="<campaign-id>")

# Start sending messages to targeted users
client.chat.start_campaign(id="<campaign-id>")

# Alternatively you can also schedule the campaign to start at a later time and stop at a specific time
import datetime
client.chat.start_campaign(
    id="<campaign-id>",
    scheduled_for=datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(hours=48),
    stop_at=datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(hours=72),
)

await campaign.create(); // create a campaign based on data passed above
await campaign.get(); // check the status of the campaign
await campaign.update({
  segment_ids: ["a869fc0f-2e7e-4fe0-8651-775c892c1718"],
  sender_id: "Updated-user-id-of-sender", // mandatory
  sender_mode: "include", // optional
  sender_visibility: "archived", // optional
  name: "Updated name (optional)",
  message_template: {
    text: "Updated Hello {{receiver.name}}!",
  },
}); // updates the campaign data

// You can start a campaign immediately, which will start sending messages to the users in the segment(s) immediately.
await campaign.start();

// Or you can schedule a campaign to start at a later time.
await campaign.start({
  // start campaign in 48 hours
  scheduledFor: new Date(Date.now() + 48 * 60 * 60 * 1000).toISOString(), // optional, campaign will start running after this time
  // automatically stop the campaign after 72 hours
  stopAt: new Date(Date.now() + 72 * 60 * 60 * 1000).toISOString(), // optional, campaign will stop running after this time
});

await campaign.stop(); // stops the campaign
await campaign.delete(); // delete the campaign

const filter = {
  segments: { $in: ["<segment-id>"] },
};
const sort = [{ field: "created_at", direction: -1 }];
const options = {
  limit: 30,
  next: "<encoded_next>",
};
const result = client.queryCampaigns(filter, sort, options); // query campaigns
// result.campaigns is an array of campaigns
// result.next is a cursor for the next page of campaigns

# Note: Campaign creation and update are not yet available in the getstream SDK.

# Get a campaign
response = client.chat.get_campaign(id="<campaign-id>")

# Start a campaign immediately
client.chat.start_campaign(id="<campaign-id>")

# Or schedule a campaign to start at a later time
import datetime
client.chat.start_campaign(
    id="<campaign-id>",
    # start campaign in 48 hours
    scheduled_for=datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(hours=48),
    # automatically stop the campaign after 72 hours
    stop_at=datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(hours=72),
)

# Stop a campaign
client.chat.stop_campaign(id="<campaign-id>")

# Query campaigns
from getstream.models import SortParamRequest
result = client.chat.query_campaigns(
    filter={"segments": {"$in": ["<segment-id>"]}},
    sort=[SortParamRequest(field="created_at", direction=-1)],
    limit=25,
)
# result.data.campaigns is a list of campaigns
# result.data.next is a cursor for the next page of results

{
  "text": "{{ sender.name }} says hello!",
  "custom": {
   "campaign_data": {{ custom }},
  },
  "attachments": [{
   "type": "image", "url": "https://path/to/image.jpg"
  }],
  "poll_id": "poll-id",
}

{
  "type": "messaging", // channel type is required
  "id": "{{receiver.id}}-{{sender.id}}",
  "team": "kansas-city-chiefs", // optional, if provided (and multi tenancy is enabled), you can limit accessibility to the channel only to a team
  "custom": {
    // optionally add custom data to channels (only when creating)
  }
}

// Query campaigns with which are scheduled or in progress
const filter = { status: { $in: ["scheduled", "in_progress"] } };
const sort = [{ field: "created_at", direction: -1 }];
const options = { limit: 10 };

// query first page
const { campaigns, next } = await client.queryCampaigns(filter, sort, options);

// query next page
const res = await client.queryCampaigns(filter, sort, { ...options, next });

from getstream.models import SortParamRequest

# Query campaigns which are scheduled or in progress
filter_options = {"status": {"$in": ["scheduled", "in_progress"]}}
sort = [SortParamRequest(field="created_at", direction=-1)]

# query first page
page1 = client.chat.query_campaigns(filter=filter_options, sort=sort, limit=10)

# query next page
page2 = client.chat.query_campaigns(filter=filter_options, sort=sort, limit=10, next=page1.data.next)

const filterStatus = { status: { $in: ["scheduled", "in_progress"] } };
const filterID = { id: { $in: ["campaign_id_1", "campaign_id_2"] } };
const filterBySegments = {
  segments: { $in: ["segment_id_1", "segment_id_2"] },
};
const filterByName = { name: { $in: ["campaign_name_1", "campaign_name_2"] } };
const filterBySender = { sender_id: { $in: ["sender_1", "sender_2"] } };
const filterByCreated = { created_at: { $gte: "2021-01-01T00:00:00Z" } };
const filterByUpdated = { updated_at: { $gte: "2021-01-01T00:00:00Z" } };

filter_status = {"status": {"$in": ["scheduled", "in_progress"]}}
filter_id = {"id": {"$in": ["campaign_id_1", "campaign_id_2"]}}
filter_by_segments = {"segments": {"$in": ["segment_id_1", "segment_id_2"]}}
filter_by_name = {"name": {"$in": ["campaign_name_1", "campaign_name_2"]}}
filter_by_sender = {"sender_id": {"$in": ["sender_1", "sender_2"]}}
filter_by_created = {"created_at": {"$gte": "2021-01-01T00:00:00Z"}}
filter_by_updated = {"updated_at": {"$gte": "2021-01-01T00:00:00Z"}}

// Let's say you have a campaign with 2000 users
const campaign = client.campaign("<campaign-id>");

// Fetch camapgin with the first 1000 users
const res1 = await campaign.get({
  users: {
    limit: 1000,
  },
});
const firstPageUsers = res1.campaign.users;

// Fetch campaign with the next 1000 users
const res2 = await campaign.get({
  users: {
    limit: 1000, // 1000 is max allowed limit
    next: res1.users.next,
    // or use prev to get previous page
    prev: res1.users.prev,
  },
});
const secondPageUsers = res2.campaign.users;

# Let's say you have a campaign with 2000 users

# Fetch campaign with the first 1000 users
res1 = client.chat.get_campaign(id="<campaign-id>", limit=1000)
first_page_users = res1.data.campaign.users

# Fetch campaign with the next 1000 users
res2 = client.chat.get_campaign(
    id="<campaign-id>",
    limit=1000,
    next=res1.data.next,
    # or use prev to get previous page
    # prev=res1.data.prev,
)
second_page_users = res2.data.campaign.users

const type = <'user'|'channel'>; // mandatory
const id = "<segment_id>"; // optional
const data = {
	filter: {
		team:'commonteam'
	},
	name: 'segment_name',
	description: 'segment_description'
} // optional

const segment = client.segment(type, id, data)

# Note: Segment creation is not yet available in the getstream SDK.
# The following operations are available:

# Get a segment
response = client.chat.get_segment(id="<segment_id>")

# Query segments
response = client.chat.query_segments(filter={"type": "user"})

# Delete a segment
client.chat.delete_segment(id="<segment_id>")

const segmentType = "user"; // mandatory
const segmentId = "<segment_id>"; // optional
const data = {
	filter: {
		//...
	}
} // optional
let userSegment = client.segment(segmentType, segmentId, data);

await userSegment.create()
await userSegment.get()
await userSegment.addTargets(userIds); // a max of 10,000 users can be added in 1 API call
await userSegment.removeTargets(userIds); // no error if doesn't exits
await userSegment.targetExists(userId); // checks if target exists in the segment
await userSegment.queryTargets(
	{ "target_id": {"$gte": <user_id>} },
	[{ field: "target_id", direction: -1 }],
	{
	 limit: 10000,
	 next: '<encoded_next>', // or prev
	}
); // queries targets in the segment
	await userSegment.delete(); // deletes segment

from getstream.models import SortParamRequest

segment_id = "<segment_id>"

# Note: Segment creation and add_targets are not yet available in the getstream SDK.

# Get a segment
client.chat.get_segment(id=segment_id)

# Remove targets from a segment
client.chat.delete_segment_targets(id=segment_id, target_ids=user_ids)

# Check if target exists in the segment
client.chat.segment_target_exists(id=segment_id, target_id=user_id)

# Query targets in the segment
client.chat.query_segment_targets(
    id=segment_id,
    filter={"target_id": {"$gte": "<user_id>"}},
    sort=[SortParamRequest(field="target_id", direction=-1)],
    limit=10000,
    next="<encoded_next>",  # or prev
)

# Delete the segment
client.chat.delete_segment(id=segment_id)

const data = {
  name: "everyone",
  all_users: true,
};
let userSegment = client.segment("user", data);
await userSegment.create();

# Note: Segment creation is not yet available in the getstream SDK.
# Use the Stream Dashboard or REST API to create a segment with all_users=True.

// note: channel template is not required for channel segment
let segmentType = "channel";
let segmentId = "segmentId";
let data = {
  name: "segment_name",
  description: "segment_description",
  filter: {
    team: "commonteam",
  },
};
let channelSegment = client.segment(segmentType, segmentId, data);
await channelSegment.create();
await channelSegment.get();
await channelSegment.addTargets(channelCids);
await channelSegment.removeTargets(channelCids);
await channelSegment.targetExists(channelCid);
await channelSegment.delete();

# Note: Segment creation and add_targets are not yet available in the getstream SDK.

segment_id = "segmentId"

# Get a segment
client.chat.get_segment(id=segment_id)

# Remove targets from a segment
client.chat.delete_segment_targets(id=segment_id, target_ids=channel_cids)

# Check if target exists in the segment
client.chat.segment_target_exists(id=segment_id, target_id=channel_cid)

# Delete the segment
client.chat.delete_segment(id=segment_id)

const data = {
  name: "All my existing chats",
  all_sender_channels: true,
};
let channelSegment = client.segment("channel", data);
await channelSegment.create();

# Note: Segment creation is not yet available in the getstream SDK.
# Use the Stream Dashboard or REST API to create a segment with all_sender_channels=True.

const segment = client.segment(segmentType, segmentId);
const response = await segment.get();

response = client.chat.get_segment(id=segment_id)

const data = {
	name: 'People in the USA'
	filter: {
		country: 'USA'
	}
};
const segment = client.segment('user', data);
await segment.create();

# Note: Segment creation is not yet available in the getstream SDK.
# Use the Stream Dashboard or REST API to create a user segment
# with filter: {"country": "USA"} and name: "People in the USA".

const campaign = client.campaign({
  segment_ids: [segment.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.create();
await campaign.start();

// Alternatively you can schedule the campaign to start at a later time.
// Also you can stop the campaign at a specific time. E.g.,
await campaign.start({
  scheduledFor: "2021-12-31T23:59:59Z",
  stopAt: "2022-01-01T23:59:59Z",
});

# Note: Campaign creation is not yet available in the getstream SDK.
# After creating a campaign via the Stream Dashboard or REST API, you can start it:

import datetime

# Start the campaign immediately
client.chat.start_campaign(id="<campaign-id>")

# Alternatively you can schedule the campaign to start at a later time.
# Also you can stop the campaign at a specific time. E.g.,
client.chat.start_campaign(
    id="<campaign-id>",
    scheduled_for=datetime.datetime(2021, 12, 31, 23, 59, 59, tzinfo=datetime.timezone.utc),
    stop_at=datetime.datetime(2022, 1, 1, 23, 59, 59, tzinfo=datetime.timezone.utc),
)

const res = await campaign.get();
console.log(res.campaign.status); // "draft" | "scheduled" | "stopped" | "completed" | "in_progress"

res = client.chat.get_campaign(id="<campaign-id>")
print(res.data.campaign.status)  # "draft" | "scheduled" | "stopped" | "completed" | "in_progress"

// await campaign.get()
{
 "id": "...",
 "stats": {
  "started_at": "2021-02-01 00:00:00",
  "completed_at": "2024-23-02 00:00:00",
  "messages_sent": 1000,
  "channels_created": 10,
  "stats_progress": 0.97,
  "stats_users_sent": 1000, // number of users the campaign message was sent to
  "stats_users_read": 567   // number of users who read the campaign message
 }
}

res = client.chat.get_campaign(id="<campaign-id>")
# res.data.campaign contains stats like:
# res.data.campaign.stats.started_at
# res.data.campaign.stats.completed_at
# res.data.campaign.stats.messages_sent
# res.data.campaign.stats.channels_created
# res.data.campaign.stats.stats_progress
# res.data.campaign.stats.stats_users_sent  # number of users the campaign message was sent to
# res.data.campaign.stats.stats_users_read  # number of users who read the campaign message

{
  "type": "campaign.started",
  "campaign": {
    "status": "running",
    "stats": {...},
    ...
  },
  "created_at": "2024-23-02 00:00:00"
}

{
  "type": "campaign.completed",
  "campaign": {
    "status": "completed",
    "stats": {...},
    ...
  },
  "created_at": "2024-23-02 00:00:00"
}

const filter = {
  name: "<name>",
};
const sort = [{ field: "created_at", direction: -1 }];
const options = {
  limit: 30,
  next: "<encoded_next>",
};
let response = await client.querySegments(filter, sort, options);

from getstream.models import SortParamRequest

response = client.chat.query_segments(
    filter={"name": "<name>"},
    sort=[SortParamRequest(field="created_at", direction=-1)],
    limit=30,
    next="<encoded_next>",
)