Targeting with TO Field

The TO field allows you to specify a list of feeds to which the activity should be copied. One way to think about it is as the CC functionality of email.

If initial activity is removed from the origin feed, it's also removed from all TO targeted feeds and origin feed followers.

Use Case: Mentions

Targeting is useful when you want to support @mentions and notify users. An example is shown below:

// Add the activity to Eric's feed and to Jessica's notification feed
var activity = new Activity("user:Eric", "tweet", "tweet:id")
{
  To = new string[] { "notification:Jessica" }
};
activity.SetData("message", "@Jessica check out getstream.io it's so dang awesome.");

await userFeed1.AddActivity(activity);
// In production use user ids, not their usernames

// Add the activity to Eric's feed and to Jessica's notification feed
const activity = {
  actor: "user:Eric",
  message: "@Jessica check out getstream.io it's awesome!",
  verb: "tweet",
  object: "tweet:id",
  to: ["notification:Jessica"],
};

const response = await user_feed_1.addActivity(activity);

# Add the activity to Eric's feed and to Jessica's notification feed
data = {
  :actor => "user:Eric",
  :message => "@Jessica check out getstream.io it's totally awesome - totally.",
  :verb => "tweet",
  :object => "tweet:id",
  :to => ["notification:Jessica", ]
}
user_feed_1.add_activity(data);

# Add the activity to Eric's feed and to Jessica's notification feed
activity = {
  "actor":"user:Eric",
  "message": "@Jessica check out getstream.io it's so dang awesome.",
  "verb":"tweet",
  "object":"tweet:id",
  "to":["notification:Jessica"]
}
user_feed_1.add_activity(activity)
# In production use user ids, not their usernames

// Add the activity to Eric's feed and to Jessica's notification feed
activity = Activity.builder()
    .actor("User:Eric")
    .verb("tweet")
    .object("tweet:id")
    .to(Lists.newArrayList(new FeedID("notification:Jessica")))
    .extraField("message", "@Jessica check out getstream.io it's so dang awesome.")
    .build();
userFeed.addActivity(activity);

// Add the activity to Eric's feed and to Jessica's notification feed
	activity := stream.Activity{
		Actor: "user:Eric",
		Verb:  "tweet",
		Object: "tweet:id",
		To: []string{
			"notification:Jessica", // In production use user ids, not their usernames
		},
		Extra: map[string]any{
			"message": "@Jessica check out getstream.io it's so dang awesome.",
		},
	}
	_, err := userFeed.AddActivity(context.TODO(), activity)
	if err != nil {
		panic(err)
	}

// Add the activity to Eric's feed and to Jessica's notification feed
$data = [
  "actor"=>"user:Eric",
  "message"=>"@Jessica check out getstream.io it's awesome!!!1",
  "verb"=>"tweet",
  "object"=>"tweet:id",
  "to"=> ["notification:Jessica"],
];

$userFeed1->addActivity($data);

The TO field is limited to a maximum of 100 targets per API request.

Use Case: Organizations & Topics

Another everyday use case is for teams, organizations or topics.

For example, one of our customers runs a football community. Updates about a player should also be added to their team's feed. Stream supports this by adding the activity to the player's feed, and specifying the target feeds in the TO field:

// The TO field ensures the activity is sent to the player, match and team feed
var activity = new Activity("Player:Suarez", "foul", "Player:Ramos")
{
  To = new string[] { "team:barcelona", "match:1" }
};
await playerFeed1.AddActivity(activity);

// The TO field ensures the activity is sent to the player, match and team feed
const activity = {
  actor: "Player:Suarez",
  verb: "foul",
  object: "Player:Ramos",
  match: { name: "El Clasico", id: 10 },
  to: ["team:barcelona", "match:1"],
};

const response = await playerFeed1.addActivity(activity);

# The TO field ensures the activity is send to the player, match and team feed
activity_data = {:actor => 'Player:Suarez', :verb => 'foul', :object => 'Player:Ramos',
  :match => {:name => 'El Clasico', :id => 10},
  :to => ['team:barcelona', 'match:1'],
}
player_feed_1.add_activity(activity_data)

# The TO field ensures the activity is send to the player, match and team feed
activity_data = {'actor': 'Player:Suarez', 'verb': 'foul', 'object': 'Player:Ramos',
  'match': {'name': 'El Clasico', 'id': 10},
  'to': ['team:barcelona', 'match:1']
}
player_feed_1.add_activity(activity_data)

// The TO field ensures the activity is send to the player, match and team feed
activity = Activity.builder()
    .actor("Player:Suarez")
    .verb("foul")
    .object("Player:Ramos")
    .to(Lists.newArrayList(new FeedID("team:barcelona"), new FeedID("match:1")))
    .extraField("match", ImmutableMap.of("El Classico", 10))
    .build();
playerFeed.addActivity(activity).join();

// The TO field ensures the activity is send to the player, match and team feed
	activity := stream.Activity{
		Actor: "Player:Suarez",
		Verb:  "foul",
		Object: "Player:Ramos",
		To: []string{
			"team:barcelona",
			"match:1",
		},
		Extra: map[string]any{
			"match": map[string]any{
				"name": "El Clasico",
				"id":  10,
			},
		},
	}
	_, err := playerFeed.AddActivity(context.TODO(), activity)
	if err != nil {
		panic(err)
	}

// The TO field ensures the activity is send to the player, match and team feed
$data = [
  'actor' => 'Player:Suarez',
  'verb' => 'foul',
  'object' => 'Player:Ramos',
  'match' => ['name' => 'El Clasico', 'id' => 10],
  'to' => ['team:barcelona', 'match:1'],
];

$playerFeed1->addActivity($data);

By default only the user, flat, aggregated and notification feed groups are set up automatically. You'll need to go to the dashboard and create feeds called team, player and match for the above example to work.

Update to targets

To targets can be updated later on to change where the activity is copied. This API requires server side auth and requires foreign id and time.

// to remove
var add = "user:1234";
feed.UpdateActivityToTargetsAsync(fidTime, new[] { add });

// to remove
var remove = "user:1234";
feed.UpdateActivityToTargetsAsync(fidTime, null, null, new[] { remove });

// to set/replace
var newOnes = new List<string>()
{
 "flat:1234",
 "user:1234",
};

feed.UpdateActivityToTargetsAsync(fidTime, null, newOnes);

// update the 'to' fields on an existing activity
// client.feed("user", "ken").function (foreign_id, timestamp, new_targets, added_targets, removed_targets)
// new_targets, added_targets, and removed_targets are all arrays of feed IDs
// either provide only the `new_targets` parameter (will replace all targets on the activity),
// OR provide the added_targets and removed_targets parameters
// NOTE - the updateActivityToTargets method is not intended to be used in a browser environment.
feed.updateActivityToTargets(foreignID, timestamp, ["feed:1234"]);
feed.updateActivityToTargets(foreignID, timestamp, null, ["feed:1234"]);
feed.updateActivityToTargets(foreignID, timestamp, null, null, ["feed:1234"]);

// Remove all old targets and set new ones (replace):
	newTargets := []string{"user:1", "user:2"}

	_, err := userFeed.UpdateToTargets(context.TODO(), activity, stream.WithToTargetsNew(newTargets...))
	if err != nil {
		panic(err)
	}

	// Add some targets and remove some others:
	add := []string{"user:1", "user:2"}
	remove := []string{"user:3", "user:4"}

	_, err := userFeed.UpdateToTargets(
		context.TODO(),
		activity,
		stream.WithToTargetsAdd(add...),
		stream.WithToTargetsRemove(remove...),
	)
	if err != nil {
		panic(err)
	}

// to add
$feed->updateActivityToTargets($foreignID, $time, [], ["feed:1234"], []);

// to remove
$feed->updateActivityToTargets($foreignID, $time, [], [], ["feed:1234"]);

// to set/replace
$feed->updateActivityToTargets($foreignID, $time, ["feed:6789"]);

# to set/replace
response = feed42.update_activity_to_targets(
 foreign_id, time, new_targets: ['user:3', 'user:2']
)

# to add/remove
response = feed42.update_activity_to_targets(
 foreign_id,
 time,
 added_targets: ['user:4', 'user:5'],
 removed_targets: ['user:3']
)

// to add/remove
feed.updateActivityToTargets(activity,
 new FeedID[] {new FeedID("feed", "1234")},
 new FeedID[] { new FeedID("feed", "abcd")});

// to set/replace
feed.replaceActivityToTargets(activity,
 new FeedID("feed", "5678"), new FeedID("feed", "efgh"));

# to add/remove
feed.update_activity_to_targets(
 foreign_id, time, added_targets=added_targets, removed_targets=removed_targets
)

# to set/replace
feed.update_activity_to_targets(foreign_id, time, new_targets=new_targets)

Rate Limits

What To Store