V2 to V3 Migration

Our team is working on an automated V2 to V3 migration system. On this page you can read what changed in the API:

V3 changes

Backend vs Client side

One of the largest changes is that in V2 we recommended a backend integration. V3 is built with both front-end and backend integrations in mind.

Users

User data on feeds 3.0 is shared with our video and chat products.

Feeds

Feeds need to be created before being used. So in the past you could add an activity to a feed and the feed would be automatically created.

In V3 you need to create the feed before adding activities to it. Feeds also have an owner which influences how client side permissions work.

SDKs

V3 comes with new SDKs so you want to use the modern SDKs.

Foreign ID vs ID

In v2 you needed to use a foreign id to indicate the uniqueness of activities and map it your system. In V3 of the API this has been replaced by making it possible to specify an ID when creating an activity

// old
feed.addActivity({ foreign_id: "update:123" });

// new
feed.addActivity({ id: "update:123" });

Activity structure

// old
activity = {
  actor: "john",
  verb: "post",
  text: "day in NYC",
  image_url: "my image",
  to: ["user:a", "user:b"],
};
// new
activity = {
  user: "john",
  type: "post",
  text: "day in NYC",
  attachments: [{ type: "image", image_url: "" }],
  feeds: ["user:a", "user:b"],
};

1000 Feed pagination limit

V2 of feeds has a limitation that you can only read up to 1000 activities in a feed. V3 has several changes related to this

You can change a feed’s activity selectors to include certain feeds or queries of activities. This means you can include popular content or content close to the user (geolocation).
It’s possible to query activities

Comments

Comments are no longer implemented with reactions. They're a separate entity, comments can be nested in any depth.

Aggregated, Notification and Flat feeds

Aggregated and notification feeds are no longer a separate feed type in V3. Aggregation and notification are now just settings on the feed. This makes it easier to switch between how your feeds work.

V3 API specification file

To following API specification files contain all feeds v3 API endpoints and the request and response schemas.

Migration guide

This guide explains how to migrate your existing Feeds v2 setup to Feeds v3 using the Stream Dashboard.

Prerequisites

Before starting the migration, complete the following steps.

1. Update Your Client Integration

First, update your application to use the Feeds v3 SDK/API.

⚠️ This step must be completed on the client side before starting the migration.
The migration process assumes your application is already compatible with Feeds v3.

2. Create a New Feeds v3 App

Create a new app configured for Feeds v3:

Go to the Dashboard.
Create a new app.
Enable the Use Feeds v3 toggle.
Select one of the supported regions.
Only regions that support Feeds v3 will be available when the toggle is enabled.

This app will be used as the destination app for the migration.

Starting the Migration

3. Open the Migration Section

From the main menu, navigate to Activity Feeds.
Click Overview.
Scroll to the bottom of the page to find the Migration section.
Click Start migration.

4. Select the Destination App

In the migration modal:

Select the destination Feeds v3 app.
This can be the app you created in the previous step.

5. Configure Reactions and Comments (Optional)

In Feeds v3, comments and reactions are separate entities. During migration, you can optionally configure how reactions are handled:

Transform reactions into comments
Choose which reaction types should be converted into comments.

Translate reaction types
For example:

Convert rocket reactions in Feeds v2 into like reactions in Feeds v3.

{
  "comments": ["comment", "reply", "subcomment"],
  "reactions": {
    "hot": "like",
    "rocket": "like",
    "thumb_down": "dislike"
  }
}

These configurations are optional but recommended to preserve the intent of existing user interactions.

6. Start the Migration

Once the configuration is complete:

Click Migrate now to begin the migration process.

Migration Phases

The migration runs automatically in the following three phases.

Phase 1: Live Traffic Replication

Incoming traffic to your Feeds v2 app is:
- Converted into Feeds v3 format
- Automatically routed to the destination Feeds v3 app
This ensures that no data is lost during the migration.

Phase 2: Export Data from Feeds v2

All existing data is gradually exported from your Feeds v2 app, including:
- Feeds
- Activities
- Reactions
- Users
- Collections
The exported data is securely stored in an S3 bucket.

Phase 3: Import Data into Feeds v3

The data exported in Phase 2 is imported into your Feeds v3 app.
This completes the historical data migration.

Completing the Migration

Once the migration is complete and your application is fully using Feeds v3:

Click Stop migration.
Switch your application to exclusively use the Feeds v3 integration.

Your migration from Feeds v2 to Feeds v3 is now complete.

Import Files

Overview