# URL Previews

## Overview

When you add an **activity** or **comment** that contains a URL in the text, Stream can automatically fetch Open Graph (OG) metadata and attach a preview. This works for both activities and comments. You can disable enrichment per request with `skip_enrich_url`.

You can also use Stream's `getOG` endpoint to fetch OG data on your own.

## Sync vs async enrichment

`async_url_enrich_enabled` is an app-level setting that controls how URL enrichment is done:

- **When enabled (async):** The server saves the activity or comment first and enriches URLs in the background. The API responds without waiting for OG scraping.
- **When disabled (sync):** The server does URL enrichment before responding, with a ~4 second timeout for OG scraping.

Configure it via `updateApp` (server-side only):

```java label="Java"
// Async enrichment: API returns immediately; OG data is attached in the background
UpdateAppRequest request = UpdateAppRequest.builder()
    .asyncUrlEnrichEnabled(true)
    .build();
common.updateApp(request).execute();

// Sync enrichment: API waits for OG scraping (up to ~4s) before responding
UpdateAppRequest syncRequest = UpdateAppRequest.builder()
    .asyncUrlEnrichEnabled(false)
    .build();
common.updateApp(syncRequest).execute();
```

## Activities with URL enrichment

```java label="Java"
AddActivityRequest request = AddActivityRequest.builder()
    .feeds(List.of("user:eric"))
    .type("post")
    .text("Check this out: https://example.com/article")
    .userID("eric")
    .build();

AddActivityResponse response = client.feeds().addActivity(request).execute().getData();
// response.getActivity().getAttachments() may include OG preview when enrichment completes
```

## Comments with URL enrichment

Comments support the same behavior: URLs in the comment text are enriched by default. Use `skip_enrich_url: true` when adding a comment to skip enrichment.

```java label="Java"
AddCommentRequest request = AddCommentRequest.builder()
    .comment("See also: https://example.com/related")
    .objectID(activityId)
    .objectType("activity")
    .userID("alice")
    .build();

client.feeds().addComment(request).execute().getData();
```

## Skipping URL enrichment

To avoid fetching OG metadata for a given activity or comment, set `skip_enrich_url` to `true`.

```java label="Java"
// Activity
AddActivityRequest activityRequest = AddActivityRequest.builder()
    .feeds(List.of("user:eric"))
    .type("post")
    .text("https://example.com/page")
    .userID("eric")
    .skipEnrichURL(true)
    .build();
client.feeds().addActivity(activityRequest).execute().getData();
// Comment
AddCommentRequest commentRequest = AddCommentRequest.builder()
    .comment("https://example.com/page")
    .objectID(activityId)
    .objectType("activity")
    .userID("alice")
    .skipEnrichURL(true)
    .build();
client.feeds().addComment(commentRequest).execute().getData();
```

## Reading URL preview attachments

Activities and comments return an `attachments` array. Enriched URL previews appear as attachments with fields such as:

- `og_scrape_url` – URL that was scraped
- `title` – OG title
- `title_link` – OG url
- `text` – OG description
- `image_url` or `thumb_url` – OG image
- `type` – e.g. `image`, `video`, or `audio`
- `asset_url` - link to the video/audio the link points to or empty

Use these fields to render link previews in your UI. Below: reading attachments from an activity and from a comment.

```java label="Java"
// From an activity
GetActivityResponse r = client.feeds().getActivity(activityId).execute().getData();
for (var a : r.getActivity().getAttachments()) {
  // use a.getTitle(), a.getImageURL(), a.getOGScrapeURL(), etc.
}

// From a comment
for (var c : r.getActivity().getLatestReplies()) {
  for (var a : c.getAttachments()) {
    // use a.getTitle(), a.getImageURL(), a.getOGScrapeURL(), etc.
  }
}
```

## URL enrichment using `getOG` endpoint

You can fetch Open Graph metadata for a URL without adding an activity or comment by calling the Get OG endpoint. This is useful if you want to show URL enrichment to users before an activity or comment is sent. You can then persist OG data in `attachments` when sending the activity or comment (make sure to set `skip_enrich_url` to avoid duplicate previews).

If OG data can't be fetched for the given URL, the API request is rejected with an error.

```java label="Java"
String url = "https://example.com/article";
GetOGResponse og = client.og().getOG(url).execute().getData();

// Activity
AddActivityRequest activityRequest = AddActivityRequest.builder()
    .feeds(List.of("user:eric"))
    .type("post")
    .text("Check this out: " + url)
    .userID("eric")
    .skipEnrichURL(true)
    .attachments(List.of(ogToAttachment(og)))
    .build();
client.feeds().addActivity(activityRequest).execute().getData();
// Comment
AddCommentRequest commentRequest = AddCommentRequest.builder()
    .comment("See also: " + url)
    .objectID(activityId)
    .objectType("activity")
    .userID("alice")
    .skipEnrichURL(true)
    .attachments(List.of(ogToAttachment(og)))
    .build();
client.feeds().addComment(commentRequest).execute().getData();
```

---

For the most recent version of this documentation, visit [https://getstream.io/activity-feeds/docs/java/url-previews/](https://getstream.io/activity-feeds/docs/java/url-previews/).