> ## 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.

# Pugpig

Integrate [Pugpig Bolt](https://www.pugpig.com/) with BeyondWords to generate [audio](/docs-and-guides/content/audio) and/or [video](/docs-and-guides/content/video) from your articles and distribute them through Pugpig apps. BeyondWords is the AI text-to-speech provider; Pugpig communicates with BeyondWords via the [API](/docs-and-guides/integrations/api-overview) and [player API](/api-reference/player/show-2), streaming the same audio URLs you use on the web.

Pugpig also maintains integration documentation at [BeyondWords text to speech (Pugpig docs)](https://docs.pugpig.com/audio/beyondwords). This guide covers the BeyondWords side of the setup.

<Tip>
  Pugpig needs your BeyondWords **Project ID** to get started. Find it in **Settings → Integrations → API** in your project dashboard.
</Tip>

## How it works

There are two common ways content reaches BeyondWords from Pugpig. Most publishers use one or both, depending on how their Bolt edition is configured.

| Path                                               | How content flows                                                      | BeyondWords setup                                                                        |
| -------------------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| [**Pugpig feed**](#pugpig-feed-path) (most common) | BeyondWords polls your Pugpig edition feed and imports articles        | [RSS Feed Importer](/docs-and-guides/integrations/rss-feed-importer) → **JSON (Pugpig)** |
| [**Pugpig Express API**](#pugpig-express-api-path) | Pugpig calls the BeyondWords API whenever a post is created or updated | Text-to-Speech plugin in Pugpig Express + [webhook](#configure-the-webhook)              |

For **native app playback**, both paths typically need a [webhook](/docs-and-guides/integrations/webhooks). When BeyondWords finishes processing an article, it notifies Pugpig. Pugpig then fetches the generated audio via the [player API](/api-reference/player/show-2) and includes it in the app feed.

```mermaid theme={null}
sequenceDiagram
    participant Pugpig as Pugpig Express / Bolt
    participant BW as BeyondWords
    participant App as Pugpig app

    Pugpig->>BW: Create or update content (API or feed import)
    BW->>BW: Generate audio/video
    BW->>Pugpig: Webhook (audio.updated)
    Pugpig->>BW: Player API — fetch audio URLs
    Pugpig->>App: narration_url + audio_meta_data in feed
```

## How Pugpig uses your audio

Once audio is available, the Pugpig Bolt Text-to-Speech plugin (via Pugpig Express) distributes it as follows—see [Pugpig's integration doc](https://docs.pugpig.com/audio/beyondwords) for full detail:

* `narration_url`—added to the `content.html` page in the app edition
* `audio_meta_data`—title and image URL added to the atom feed

Pugpig calls the BeyondWords player API and uses the `audio` array from the response. It uses the entry with `content_type: audio/mpeg` (the `.mp3` file) and ignores the `application/x-mpegURL` stream (`.m3u8`).

<Info>
  If audio has not finished generating when Pugpig first fetches the player API, the `audio` array may be empty. Pugpig can fetch again when the article is subsequently updated, or once the [`audio.updated`](/docs-and-guides/integrations/webhooks#audioupdated) webhook fires and Pugpig re-queries the API.
</Info>

## Choose your integration path

### Pugpig feed path

Use this when your Pugpig edition exposes a **JSON (Pugpig)** feed—the most common setup for Bolt clients.

1. Set up the [RSS Feed Importer](/docs-and-guides/integrations/rss-feed-importer) with feed type **JSON (Pugpig)**
2. Configure [page extraction](/docs-and-guides/integrations/rss-feed-importer#how-does-page-extraction-work) and field mapping as needed
3. Optionally enable **Restrict to articles marked for audio in Bolt CMS** to import only stories with `BeyondwordsCreateAudio` set in `custom_analytics`
4. Configure the [webhook](#configure-the-webhook) so Pugpig apps receive audio when generation completes

### Pugpig Express API path

Use this when Pugpig sends content directly to BeyondWords through the **Text-to-Speech plugin** in Pugpig Express—rather than (or in addition to) the feed importer.

Follow the steps below, then configure the [webhook](#configure-the-webhook).

## Pugpig Express API path

<Steps>
  <Step title="Copy your project ID">
    Go to **Settings → Integrations → API** in your project dashboard and copy the **Project ID**.
  </Step>

  <Step title="Share your project ID with Pugpig">
    Open the **Text-to-Speech** plugin in Pugpig Express and paste your BeyondWords **Project ID** into the relevant field.

    Pugpig will call the BeyondWords API each time a post is created or updated. See [Pugpig's setup guide](https://docs.pugpig.com/audio/beyondwords#what-do-we-need-from-you-to-get-set-up) for plugin-specific steps.
  </Step>

  <Step title="Configure the webhook">
    See [Configure the webhook](#configure-the-webhook) below — required for Pugpig to know when audio generation is complete.
  </Step>

  <Step title="Publish as normal">
    Publish or update articles in Pugpig as normal. BeyondWords generates audio/video as per your project settings. Once processing completes, Pugpig is notified via webhook and fetches the audio URLs from the player API.
  </Step>
</Steps>

## Configure the webhook

Pugpig Express exposes a webhook endpoint that listens for BeyondWords notifications and updates app content once audio is ready.

<Steps>
  <Step title="Get your Pugpig webhook URL">
    Your Pugpig Express site provides a webhook URL in this format:

    ```text theme={null}
    https://{your-site}.express.pugpig.com/wp-json/pugpig/beyondwords/webhook/audio-update/
    ```

    Replace `{your-site}` with your Express site subdomain. Pugpig documents this endpoint in their [webhook configuration guide](https://docs.pugpig.com/audio/beyondwords#configure-webhook-endpoint-in-beyondwords).
  </Step>

  <Step title="Add the webhook in BeyondWords">
    Go to **Settings → Webhooks** in your BeyondWords project dashboard.

    Click **+ Webhook** and paste your Pugpig webhook URL into **Webhook URL**.

    Toggle **Enabled** on, then click **Save changes**.

    BeyondWords sends an [`audio.updated`](/docs-and-guides/integrations/webhooks#audioupdated) event when generation completes successfully.
  </Step>

  <Step title="Add request headers (optional)">
    If Pugpig's webhook endpoint requires authentication, add the required **Header name** and **Header value** pairs in the webhook settings.
  </Step>

  <Step title="Enable static IP (optional)">
    If Pugpig's endpoint requires IP allowlisting, enable **Static IP** on the webhook and allowlist the displayed address in Pugpig's firewall configuration.

    <Info>
      Webhook requests are sent from `20.234.8.180` when static IP is enabled.
    </Info>
  </Step>
</Steps>

## Fine-tuning

* [Content extraction](/docs-and-guides/integrations/content-extraction)—when using the [Pugpig feed path](#pugpig-feed-path), [content filters](/docs-and-guides/integrations/content-extraction#filters) apply to imported HTML
* [Data attributes](/docs-and-guides/integrations/data-attributes)—per-article metadata and segment control in HTML
* [Voices](/docs-and-guides/voices/overview) and [player settings](/docs-and-guides/distribution/player/player-settings)—project defaults in the BeyondWords dashboard
* [Web player](/docs-and-guides/distribution/player/installation/javascript-sdk)—install separately on your website if you want web playback in addition to the Pugpig app

## FAQs

<AccordionGroup>
  <Accordion title="Should I use the Pugpig feed or the Express API?">
    **Pugpig feed** (via the [RSS Feed Importer](/docs-and-guides/integrations/rss-feed-importer)) is the most common path for Bolt edition clients. **Pugpig Express API** (Text-to-Speech plugin) is used when Pugpig pushes content directly on post create/update. Some publishers use both. Either way, configure a [webhook](#configure-the-webhook) for native app distribution.
  </Accordion>

  <Accordion title="Does audio appear immediately after publishing?">
    Not always. Generation typically takes a few minutes. If Pugpig queries the player API before audio is ready, the `audio` array may be empty — a [known behaviour documented by Pugpig](https://docs.pugpig.com/audio/beyondwords#known-issues). Once the webhook fires or the article is updated again, Pugpig can fetch the completed audio.
  </Accordion>

  <Accordion title="Can I restrict which articles get audio?">
    Yes. For the **Pugpig feed** path, enable **Restrict to articles marked for audio in Bolt CMS** in the [RSS Feed Importer](/docs-and-guides/integrations/rss-feed-importer) page extraction settings. BeyondWords only imports  stories where `custom_analytics.BeyondwordsCreateAudio` is set in the Pugpig feed.
  </Accordion>
</AccordionGroup>