Activities

Creating Activities

The example below shows how to create an activity and add it to a feed.

// Add an activity to 1 feed or multiple feeds
$activity = new GeneratedModels\AddActivityRequest(
    type: 'post',
    feeds: ['user:1', 'stock:apple'],
    text: 'apple stock will go up',
    userID: '<user id>',
    custom: (object)[
        'test_field' => 'test_value',
        'timestamp' => time()
    ]
);
$response = $feedsClient->addActivity($activity);

The above example was quite simple. Here are a few more examples:

Image & Video

$activity = new GeneratedModels\AddActivityRequest(
    type: 'post',
    feeds: ['user:1'],
    text: 'look at NYC',
    userID: '<user id>',
    attachments: [
        new GeneratedModels\Attachment(
            imageUrl: 'https://example.com/image.png',
            type: 'image',
            custom: (object)[]
        )
    ]
);
$response = $feedsClient->addActivity($activity);

Sharing activities

When creating an activity, it's possible to set parent_id; setting this field will increase the share_count of the parent activity. This feature lets you implement "retweets".

When reading an activity with parent id set, you can access the parent activity with activity.parent.

$activity = new GeneratedModels\AddActivityRequest(
    type: 'post',
    feeds: ['user:1'],
    text: 'Couldn\'t agree more!',
    parentID: '<activity to share>',
    userID: '<user id>',
);
$response = $feedsClient->addActivity($activity);

Restricting comment replies

When creating an activity it's possible to set who can add comments. Possible options:

• Everyone (this is the default setting)
• Only people I follow
• Nobody

$activity = new GeneratedModels\AddActivityRequest(
    type: 'post',
    feeds: ['user:1'],
    text: 'apple stock will go up',
    userID: '<user id>',
    restrictReplies: 'people_i_follow' // Options: 'everyone', 'people_i_follow', 'nobody'
);
$response = $feedsClient->addActivity($activity);

Activity request options

The following options can be provided when creating an activity:

AddActivityRequest

Activity size limit

Total activity size (including built-in and custom fields) must not exceed 10KB (the limit is checked when writing activities, not when reading them). If your use case requires a larger payload, collections help attach data to activities without increasing activity size.

Reading Activities with Enrichment

When you read activities from feeds, they are automatically enriched with additional data:

• Comments: The latest 5 top-level comments (replies not included by default)
• Reactions: Recent reactions and reaction counts
• User data: Information about the activity author
• Collections: Any collections the activity references

To load more comments, replies, or additional data, use the dedicated loading methods described in the Comments and Reactions sections.

Translation

Activity text can be translated on demand and projected when reading feeds and activities. See Translation for translate endpoints, read-time language projection, and the i18n object format.

Overview of All Activity Fields

ActivityResponse

Adding Many Activities

You can also batch add activities. Here's an example:

$activities = [
    [
        'feeds' => ['user:123'],
        'id' => '1',
        'type' => 'post',
        'text' => 'hi',
        'user_id' => '<user id>',
    ],
    [
        'feeds' => ['user:456'],
        'id' => '2',
        'type' => 'post',
        'text' => 'hi',
        'user_id' => '<user id>',
    ]
];

$response = $feedsClient->upsertActivities(
    new GeneratedModels\UpsertActivitiesRequest(activities: $activities)
);

Visibility Levels

When creating an activity, you can set a visibility level for the activity:

• public: marks the activity as public - everyone who can view feed content, can see it
• private: marks the activity as private - only feed owner can see it
• tag:mytag: marks the activity as only visible to followers/members with the permission to see this tag

This visibility system is very flexible and allows you to build:

• Apps like Patreon where only certain levels of users can see your content
• Apps like Strava where it's possible to share your activity with nobody, everyone or your followers

$feedsClient->addActivity(
    new \GetStream\GeneratedModels\AddActivityRequest(
        feeds: ['user:1'],
        type: 'post',
        text: 'Premium content',
        visibility: 'tag',
        visibilityTag: 'premium',
        userID: '<user id>'
    )
);
// Premium users can see full activity, others a preview

For all the details on tag visibility read the Membership levels guide.

Partial activity updates

A partial update can be used to set or unset specific fields and leave other fields unchanged (also known as a patch-style update). Both set and unset can be used in the same request. The dotted-notation is also available for both set and unset for the custom field.

// Partially set some fields
$response = $feedsClient->updateActivityPartial(
    '123',
    new GeneratedModels\UpdateActivityPartialRequest(
        userID: '<user id>',
        set: [
            'text' => 'Japan has over 6,800 islands.',
        ]
    )
);
echo 'Activity edited at: ' . $response->getActivity()->getEditedAt();

// Partially unset some fields
$response = $feedsClient->updateActivityPartial(
    '123',
    new GeneratedModels\UpdateActivityPartialRequest(
        userID: '<user id>',
        unset: ['custom.color']
    )
);
echo 'Activity edited at: ' . $response->getActivity()->getEditedAt();

Batch Partial Activity Updates

You can perform partial updates on multiple activities in a single batch operation. This is more efficient than updating activities one by one when you need to update several activities at once.

// Update multiple activities with different changes
var partialUpdateRequest = new UpdateActivitiesPartialBatchRequest
{
    Changes = new List<UpdateActivityPartialChangeRequest>
    {
        new UpdateActivityPartialChangeRequest
        {
            ActivityID = activityId1,
            Set = new Dictionary<string, object>
            {
                ["text"] = "Updated text for activity 1",  // Update main text
                ["likes"] = 25,  // Update custom field
                ["status"] = "featured"  // Update custom field
            },
            Unset = new List<string> { "priority" }  // Remove custom field
        },
        new UpdateActivityPartialChangeRequest
        {
            ActivityID = activityId2,
            Set = new Dictionary<string, object>
            {
                ["text"] = "Updated text for activity 2",  // Update main text
                ["likes"] = 15,  // Update custom field
                ["status"] = "published"  // Update custom field
            },
            Unset = new List<string> { "views", "category" }  // Remove multiple custom fields
        }
    }
};

var response = await _feedsV3Client.UpdateActivitiesPartialBatchAsync(partialUpdateRequest);
Console.WriteLine($"Updated {response.Data.Activities.Count} activities");

This operation allows you to:

• Update specific fields in multiple activities
• Use both set (to update/add fields) and unset (to remove fields) operations
• Process all changes in a single API call for better performance

Updatable Fields:

The following reserved fields can be updated:

• text - Activity text content
• attachments - Media attachments
• visibility - Activity visibility level
• visibility_tag - Visibility tag
• expires_at - Expiration timestamp
• filter_tags - Filter tags for querying
• interest_tags - Interest tags
• collection_refs - Collection references
• feeds - Feeds the activity belongs to
• mentioned_user_ids - Mentioned users
• poll_id - Associated poll
• Any custom fields (stored in custom object)

Note: The type field cannot be changed after an activity is created. Other immutable fields include id, user_id, created_at, etc.

Updating Activities

This example shows how to fully update an activity:

// NOTE: updateActivity does a full replace of the activity.
// Use updateActivityPartial if you only want to update specific fields.
$response = $feedsClient->updateActivity(
    '123',
    new GeneratedModels\UpdateActivityRequest(
        text: 'Updated text',
        userID: '<user id>'
    )
);
echo 'Activity edited at: ' . $response->getActivity()->getEditedAt();

Deleting Activities

This example shows how to delete an activity:

// Delete an activity (soft delete sets deleted_at but retains the data, hard delete fully removes it)
$response = $feedsClient->deleteActivity('123', false);

// Batch delete activities
$response = $feedsClient->deleteActivities(
    new GeneratedModels\DeleteActivitiesRequest(
        ids: ['123', '456'],
        userID: '<user id>',
        hardDelete: false
    )
);

Restore Activity

If an activity was soft-deleted, it can be restored using the restore endpoint. Only the activity owner can restore their own activities (for client-side requests). Hard-deleted activities cannot be restored.

// Restore a soft-deleted activity
$response = $feedsClient->restoreActivity(
    '123',
    new GeneratedModels\RestoreActivityRequest(
        userID: '<user id>'
    )
);

When an activity is restored, a feeds.activity.restored event is sent to all feeds the activity is part of. There is no default event handler in client-side SDKs but it's possible to add a custom handler.

Get activity

Fetching a single activity.

When implementing an activity details page on the client-side, it may be important to receive updates for the activity. The activity state is automatically updated on HTTP requests initiated from the client. To receive real-time updates (to receive updates from other users, for example someone else liked this post), you have to watch the feed the activity belongs to (or one of the feeds, in case it belongs to multiple feeds).

When fetching an activity that belongs to multiple feeds, activity.current_feed will be empty. If you wish to display feed information alongside the activity, you have to fetch any of the containing feeds with a separate API call.

const activityWithStateUpdates =
  client.activityWithStateUpdates(activityId);
await activityWithStateUpdates.get({
  // Optionally fetch comments too
  comments: {
    limit: 10,
    depth: 2,
  },
});

// Subscribe to state updates
activityWithStateUpdates.state.subscribe((state) => {
  console.log(state.activity);
  console.log(state.comments_by_entity_id);
  // True if activity is being fetched
  console.log(state.is_loading);
});
// Comment pagination
activityWithStateUpdates.loadNextPageActivityComments;
activityWithStateUpdates.loadNextPageCommentReplies;

// Optionally start watching the feed
// If activity belongs to multiple feeds, it's up to you to choose which feed to watch
const fid = activityWithStateUpdates.currentState.activity!.feeds[0];
const [group, id] = fid.split(':');
const feed = client.feed(group, id);
let shouldWatch = false;
if (!feed.currentState.watch) {
  await feed.getOrCreate({
    watch: true,
    limit: 0,
    followers_pagination: { limit: 0 },
    following_pagination: { limit: 0 },
  });
}

// When leaving the page...
// Dispose the activity; this avoids refetching the activity if WebSocket reconnects
activityWithStateUpdates.dispose();
// You should stop watching the feed, unless your app has another component that watches the same feed
if (shouldWatch) {
  await feed.stopWatching();
}

// If you don't care about state updates, no need to call activityWithStateUpdates
await client.getActivity({
  id: activityId,
});

Adding activities to multiple feeds

The Stream API allows you to post an activity to multiple feeds, the maximum is 25.

When an activity is posted to multiple feeds, activity.current_feed field is only set when reading a feed (feed.getOrCreate):

• When reading with current selector, it's set to the feed we're reading
• For any other selector it'll be one of the feeds the activity is posted to
  • If the user follows one of the feeds, it's set to the followed feed (if more than one feed is followed, it'll be one of the feeds)
• For all other API calls (for example queryActivities, getActivity) and WebSocket events it's not set

// Add an activity to 1 feed or multiple feeds
$activity = new GeneratedModels\AddActivityRequest(
    type: 'post',
    feeds: ['user:1', 'stock:apple'],
    text: 'apple stock will go up',
    userID: '<user id>',
    custom: (object)[
        'test_field' => 'test_value',
        'timestamp' => time()
    ]
);
$response = $feedsClient->addActivity($activity);

Activity list controls - client-side SDKs

Client-side SDKs allow controlling when and where to add new activities as they arrive. By default, only activities added by the current user and matching the filter provided to getOrCreate are added to the list (this is how social media apps usually work), and these activities are added to the start of the list. But it's possible to override this behavior:

import { activityFilter } from "@stream-io/feeds-client";

const feed = client.feed("user", userId, {
  onNewActivity: ({ activity, currentUser }) => {
    const requestConfig = feed.currentState.last_get_or_create_request_config;
    if (!activityFilter(activity, requestConfig)) return "ignore";
    return activity.user.id === currentUser?.id ? "add-to-start" : "ignore";
  },
});