Embed

API Reference

Complete reference for the Activoice embed configuration

`Activoice.init(config)`

Initializes one embed instance inside the target container.

If the container already contains an active embed (for example after a client-side navigation), it is destroyed and replaced with a fresh instance.

window.Activoice.init(config: ActivoiceEmbedConfig): void

`ActivoiceEmbedConfig`

The root configuration object passed to Activoice.init().

Property	Type	Required	Description
`container`	`string`	✓	CSS selector of the host element (e.g. `'#av-embed-container'`). Must match exactly one element in the DOM at the time `init()` is called.
`campaignId`	`string`	✓	Slug or identifier of the campaign to embed. Visible in your Activoice admin, in the campaign URL and in the campaign's Share panel, Embed tab.
`embedOptions`	`EmbedOptions`	—	Optional display and behavior settings.
`campaignOverrides`	`CampaignOverrides`	—	Optional overrides applied on top of the campaign configuration defined in your Activoice admin.

`EmbedOptions`

All fields are optional. Omitting a field uses the default value.

Property	Type	Default	Description
`spinnerColor`	`string`	`'#fed13a'`	CSS color of the loading spinner shown before the campaign is ready. Accepts any valid CSS color value (hex, `rgb()`, named colors, etc.).
`initialPage`	`'steps' \| 'landing'`	`'steps'`	Controls which page of the campaign is shown first. `'steps'` opens directly on the action flow. `'landing'` shows the campaign landing page.
`displayMode`	`'inline' \| 'fullHeight'`	`'inline'`	Height management strategy. `'inline'` updates the iframe height in pixels each time the content resizes. `'fullHeight'` sets `height: 100%` so the iframe fills its container — useful in sidebars or fixed-height panels.
`withToolbar`	`boolean`	`false`	Renders the navigation toolbar inside the embed (back button, step indicator). Disabled by default for a seamless embedded look.
`withBackground`	`boolean`	`false`	Paints the campaign's background color, or the `color_background` override, on the iframe body. When disabled, the background is transparent so the host page shows through. Text and UI elements automatically switch to a light color when the background color is dark.
`withPadding`	`boolean`	`false`	Adds horizontal padding to the campaign content area.
`bypassCampaignStateCheck`	`boolean`	`false`	When `true`, the campaign renders even if it is in `draft` or `ended` state. Intended for preview and testing purposes only — do not enable in production.

`CampaignOverrides`

Overrides applied on top of the campaign configuration defined in your Activoice admin.

interface CampaignOverrides {
  recipients?: Recipient[]        // Global recipient override for all interpellations
  interpellations?: Array<{
    id: string                    // UUID of the interpellation to override
    recipients?: Recipient[]      // Per-interpellation override (takes priority)
  }>
  color_background?: string       // #rrggbb, surface the embed sits on
  color_main?: string             // #rrggbb, brand color
  color_buttons?: string          // #rrggbb, call-to-action buttons
  custom_css?: string             // Replaces the organization's custom CSS, '' removes it
}

Recipient resolution order

Recipients are resolved per interpellation with the following priority:

Per-interpellation override — interpellations[].recipients if provided for that entry
Root-level override — top-level recipients applied to all interpellations that don't have their own override
Admin configuration — original recipients preserved when no override applies

When interpellations is provided, only the listed interpellations are shown — any interpellation whose id is not included is hidden from the embed. Omit interpellations entirely to keep all interpellations visible.

The root-level recipients is a convenient shortcut when you want to set the same recipients across all interpellations without repeating them in each entry.

Design fields

Each design field replaces the organization's value from your Activoice admin; an omitted field keeps it.

Field	Type	Description
`color_background`	`string`	`#rrggbb` color of the surface the embed sits on. Drives the text color and derived surfaces; painted on the body only with `embedOptions.withBackground`.
`color_main`	`string`	`#rrggbb` brand color: landing gradient, toolbar, links, focus states.
`color_buttons`	`string`	`#rrggbb` color of the call-to-action buttons; the label color is picked for contrast.
`custom_css`	`string`	Replaces the organization's custom CSS; `''` removes it. Checked before it is applied: no external URL, Google Fonts `@import` only, 50 000 characters at most.

A color that is not #rrggbb, null included, or a custom_css that is not a string is ignored with a warning in the browser console and the organization's value stays. A CSS that fails a check is dropped entirely, with a warning too.

`Recipient`

All fields are optional.

Field	Type	Description
`first_name`	`string`	First name of the recipient.
`last_name`	`string`	Last name of the recipient.
`gender`	`'M' \| 'F' \| 'O'`	Gender: `M` (male), `F` (female), `O` (other / not specified). Used to personalize AI-generated messages.
`display_title`	`string`	Title or role displayed to the user (e.g. `'Mayor of Lyon'`).
`photo_url`	`string \| null`	Absolute URL of the recipient's photo.
`email`	`string \| null`	Email address (used for email interpellation modes).
`phone_number`	`string \| null`	Phone number (used for call interpellation modes).
`personal_link`	`string \| null`	Absolute URL to the recipient's personal or professional website.
`facebook_page`	`string`	Absolute URL of the recipient's Facebook page.
`twitter_handle`	`string`	Twitter/X handle, without the `@` prefix.
`instagram_handle`	`string`	Instagram handle, without the `@` prefix.
`linkedin_page`	`string`	Absolute URL of the recipient's LinkedIn profile.
`tiktok_handle`	`string`	TikTok handle, without the `@` prefix.
`geo_type`	`string \| null`	Type of geographic area (e.g. `'municipality'`, `'department'`). Used for geospatial targeting when supporters search by location.
`geo_id`	`string \| null`	Identifier of the geographic area, matching the `geo_type` taxonomy.
`party_name`	`string \| null`	Full name of the political party.
`party_short_name`	`string \| null`	Abbreviated party name displayed in the UI.
`custom_fields`	`Record<string, string>`	Arbitrary key-value pairs injected as extra variables into AI-generated message templates.

TypeScript types

Download the type definitions file and reference it in your project for full IDE autocompletion: activoice-embed.d.ts

This file is not versioned or distributed automatically. As the API evolves, you will need to re-download it and update your local copy manually.

Then point your tsconfig.json to it:

tsconfig.json

{
  "include": ["./activoice-embed.d.ts", "src/**/*"]
}

Integration Guide

Embed an Activoice campaign on any website in minutes

Campaign Reference

Read a campaign's public data from your own website