Add a Voice AI Agent to Gatsby (gatsby-ssr or Script)

AnveVoice

Add a Voice AI Agent to Gatsby (gatsby-ssr or Script)

Add the AnveVoice voice agent to a Gatsby site with onRenderBody in gatsby-ssr.js or the built-in Script component: strategies, build checks, limits.

How to add AnveVoice to a Gatsby site

In Gatsby, add the AnveVoice tag with onRenderBody in gatsby-ssr.js so it is written into every built page, or use Gatsby's Script component in a layout. Test with a production build, because the SSR API runs at build time. Steps checked against the official documentation on 2026-10-14.

At a glance

Where the code goes: gatsby-ssr.js (onRenderBody) or a layout using Script from gatsby
Script component: Added in [email protected]; strategies post-hydrate, idle, off-main-thread
Coding needed: About ten lines of JavaScript or JSX
Test with: gatsby build then gatsby serve

Before you start

Copy your embed ID from app.anvevoice.app. The Free plan costs $0 and needs no card. Gatsby has two supported ways to add a third-party script, and both are in the official docs: a server-side rendering API that writes elements into the generated HTML, and the Script component for use in React code. Pick one. The SSR route gives you a single file edit that covers every page the site generates. The component route fits teams that already render a shared Layout component and want Gatsby to control when the script loads.

Method 1: onRenderBody in gatsby-ssr.js

Gatsby's SSR API reference explains that onRenderBody runs after each page is server-rendered during the build, and that setHeadComponents adds elements to the head of the generated html.js. Its own example adds a script element that way. Because the elements are React components in an array, each needs a unique key.

1. Create or open gatsby-ssr.js — It lives in the project root next to gatsby-config.js. The file can also be gatsby-ssr.tsx.
2. Add the head component — Export onRenderBody and pass the AnveVoice script to setHeadComponents. The async attribute lets the browser keep parsing while it downloads. Code: // gatsby-ssr.js const React = require("react") exports.onRenderBody = ({ setHeadComponents }) => { setHeadComponents([ <script key="anvevoice-embed" src="https://anvevoice.app/embed.js?embedId=YOUR_EMBED_ID" async />, ]) }
3. Build and serve — Run gatsby build, then gatsby serve, and check the page. The element is written during the build, so the tag is baked into each HTML file.

Method 2: Gatsby's Script component

Gatsby added a Script component in version 4.15.0, imported from the gatsby package, as a drop-in replacement for a lowercase script tag. Its strategy prop has three values: post-hydrate (the default, loads after the page hydrates), idle (loads after hydration once the main thread is free) and off-main-thread (experimental, runs in a web worker through Partytown). For a voice button, idle is a considerate choice because the page becomes interactive first. Avoid off-main-thread: Gatsby notes those scripts load only on server-rendered navigation, not on client-side Link navigation, which is the opposite of what a site-wide widget needs.

1. Add Script to your layout — Import Script from gatsby and render it after children in the component that wraps every page. Code: // src/components/layout.js import * as React from "react" import { Script } from "gatsby" export default function Layout({ children }) { return ( <> {children} <Script src="https://anvevoice.app/embed.js?embedId=YOUR_EMBED_ID" strategy="idle" /> </> ) }
2. Make sure every page uses the layout — If some pages skip the Layout component, they will not load the tag. Gatsby also supports Script inside wrapPageElement and wrapRootElement, and recommends mirroring those in both gatsby-browser.js and gatsby-ssr.js.

Which method should you pick?

onRenderBody: one file, independent of components, works for every generated page. Good for a pure site-wide tag.
Script component: loading strategy control, easier to remove from a single layout, and it can be shown only on pages that render it.
Do not use both at once. AnveVoice ignores a second copy on the same page, but duplicate code is confusing to maintain.

Check that it works

1. Run a production build — Run gatsby build and gatsby serve. The SSR API is a build-time step, so the development server is not a reliable check.
2. Inspect the output — Open view-source on a built page and search for anvevoice.app/embed.js.
3. Test voice — Click the round microphone button bottom-right, allow microphone access and ask a question.

Common problems

Tag absent in gatsby develop: test on the built site instead.
Key warning from React: the element passed to setHeadComponents needs a unique key prop.
Callbacks do nothing: Gatsby says onLoad and onError do not work with inline scripts or off-main-thread scripts, so avoid them for this install.
Microphone blocked: the deployed site must be on HTTPS and must not send a Permissions-Policy header that disables the microphone.

Sources

Gatsby Docs: Gatsby SSR APIs (onRenderBody) (https://www.gatsbyjs.com/docs/reference/config-files/gatsby-ssr/) — checked 2026-10-14
Gatsby Docs: Gatsby Script API (https://www.gatsbyjs.com/docs/reference/built-in-components/gatsby-script/) — checked 2026-10-14

Try AnveVoice on your site

Free plan: $0, 50,000 tokens a month, no card. Get your embed ID in the dashboard, then paste one tag.