> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beyondwords.io/llms.txt
> Use this file to discover all available pages before exploring further.

# RSS Feed Importer

The RSS feed importer polls your feeds and imports published articles into BeyondWords, where they're converted into [audio](/docs-and-guides/content/audio) and/or [video](/docs-and-guides/content/video) as per your project settings.

Unlike [Magic Embed](/docs-and-guides/integrations/magic-embed) or the [WordPress](/docs-and-guides/integrations/publishing-platforms/wordpress) and [Ghost](/docs-and-guides/integrations/publishing-platforms/ghost) plugins, the RSS Feed Importer does not install the player automatically—see [How do I embed the player?](#how-do-i-embed-the-player-on-my-website) below.

<Tip>
  We recommend mapping **Source ID** to your CMS article ID wherever possible. This makes it easier to embed the player with `sourceId`, search for content in the dashboard, and use platform features that key off `source_id`.
</Tip>

## How it works

BeyondWords checks your configured feeds every 10 minutes for new or updated articles. When it finds changes, it imports the content and starts audio/video generation. See the [FAQs](#faqs) for how update detection, page extraction, and feed management work.

## Feed types

| Type              | Use for                                                                                                                                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **XML**           | Standard RSS or Atom feeds                                                                                                                                                                                    |
| **JSON**          | Generic JSON feeds                                                                                                                                                                                            |
| **JSON (Pugpig)** | Pugpig Bolt edition feeds—the most common way Pugpig clients provide content to BeyondWords. See the [Pugpig integration guide](/docs-and-guides/integrations/publishing-platforms/pugpig) for webhook setup. |

## Add a new feed

<Steps>
  <Step title="Start a new feed">
    Go to **Settings → Integrations → RSS Feed Importer** in your project dashboard.

    Then, click **+ Feed**.
  </Step>

  <Step title="Select feed type">
    Select the type of feed you want to add: **XML**, **JSON**, or **JSON (Pugpig)**. See [feed types](#feed-types) above for guidance.
  </Step>

  <Step title="Add feed URL">
    Enter the URL of your RSS or JSON feed.
  </Step>

  <Step title="Set request headers (optional)">
    For paywalled or protected content, configure authentication headers so BeyondWords can access your feed and article pages.

    1. Add a **Header name** and **Header value**
    2. Click **+** to add additional headers if needed
    3. Click **Save changes**

    <Info>
      Requests will be made with `User-Agent: BeyondWords Importer`
    </Info>
  </Step>

  <Step title="Configure page extraction (optional)">
    On the **Page extraction** step, configure how BeyondWords handles article content:

    * **Fetch content from article URLs**: If your feed only contains article links rather than full text, switch this on so BeyondWords can fetch and extract content from those pages.
    * **Restrict to articles marked for audio in Bolt CMS**: Only available when feed type is JSON (Pugpig). Switch this on to import only articles explicitly marked for audio in Bolt CMS. When off, all qualifying articles in the feed are converted to audio.

    Once complete, click **Continue**.
  </Step>

  <Step title="Map the feed">
    Map fields from your feed to BeyondWords article properties. The dashboard shows the fields detected in your feed—select the matching one for each property below.

    For a typical RSS feed, the usual mappings are:

    | BeyondWords property | Typical feed field             |
    | -------------------- | ------------------------------ |
    | Title                | `title`                        |
    | Body                 | `content` or `content:encoded` |
    | Source ID            | `guid`                         |
    | Source URL           | `link`                         |
    | Summary              | `description`                  |
    | Author               | `author` or `dc:creator`       |
    | Publish date         | `pubDate`                      |

    **Required:** Body, Source ID

    **Optional:** Title, Source URL, Summary, Author, Image URL, Metadata

    Map **Publish date** to `pubDate` if you want BeyondWords to [detect article updates](#how-does-beyondwords-detect-article-updates)—we recommend always including it.

    If **Fetch content from article URLs** is enabled, leave Body unmapped—BeyondWords will extract content from the page instead. Map **Source URL** to `link` so BeyondWords knows which page to fetch.
  </Step>

  <Step title="Save and activate">
    Click **Save changes** to complete setup. Your feed will be enabled automatically and BeyondWords will begin checking for articles.
  </Step>
</Steps>

<Note>
  If your website requires IP allowlisting, enable static IP in your [extraction settings](/docs-and-guides/integrations/content-extraction).
</Note>

You can also manage RSS feed imports via the [RSS feed importer API](/api-reference/rss-feed-importer/list).

* BeyondWords will automatically check your feed every 10 minutes for new or updated articles
* You can manually trigger an import by clicking the **⋯** button next to your feed and selecting **Run**
* New articles will be processed and converted to audio automatically
* Updated articles (detected by changes in the publish date) will be updated automatically

## FAQs

<AccordionGroup>
  <Accordion title="How do I embed the player on my website?">
    Install the [player](/docs-and-guides/distribution/player/player-introduction) separately using the [JavaScript](/docs-and-guides/distribution/player/installation/javascript-sdk), [iOS](/docs-and-guides/distribution/player/installation/ios-sdk), or [Android](/docs-and-guides/distribution/player/installation/android-sdk) SDK. Use the **Source ID** or **Source URL** from your feed mapping to load the correct content—for example, `sourceId` in the player configuration.
  </Accordion>

  <Accordion title="How does BeyondWords detect article updates?">
    BeyondWords uses the mapped **Publish date** field (typically `pubDate`) to detect when an article has been updated. Each time the feed is pulled, BeyondWords compares the publish date in the feed against the value stored from the last import. If the new date is later than what was stored before, the article is re-fetched and its audio/video is regenerated.

    When you revise an article, your feed should return an updated `pubDate`. If the publish date stays the same, BeyondWords treats the article as unchanged and will not re-import it.

    Articles must remain in the feed for BeyondWords to see their publish dates on each pull. If an article drops out of the feed, we can no longer check whether it has been updated.
  </Accordion>

  <Accordion title="How often is my feed checked?">
    BeyondWords automatically checks your feed every 10 minutes for new or updated articles. You can also manually trigger an import by clicking **⋯** next to your feed and selecting **Run**.
  </Accordion>

  <Accordion title="How does page extraction work?">
    When **Fetch content from article URLs** is enabled, BeyondWords fetches the full article HTML from the URL in your feed and extracts editorial content using your project's [extraction settings](/docs-and-guides/integrations/content-extraction).

    [Automatic extraction](/docs-and-guides/integrations/content-extraction#automatic-extraction) works well for many sites, but most publishers also set up [content filters](/docs-and-guides/integrations/content-extraction#filters) to exclude recurring page elements (newsletter sign-ups, related-article blocks, etc.) or include specific containers. Configure filters in **Settings → Extraction → Filters**. You can also use [data attributes](/docs-and-guides/integrations/data-attributes) for precise control over metadata.
  </Accordion>
</AccordionGroup>

## Getting help

If you encounter issues or have questions, [contact support](/docs-and-guides/support/get-support).