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 the backoffice URL and in the embed panel.
`embedOptions`	`EmbedOptions`	—	Optional display and behavior settings.
`campaignOverrides`	`CampaignOverrides`	—	Optional overrides applied on top of the campaign configuration defined in the backoffice.

`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`	Applies the campaign's background color to the iframe body. When disabled, the background is transparent so the host page shows through.
`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 the backoffice.

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)
  }>
}

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

`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