API Reference

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().

* Exactly one of campaignId and petitionId. Both, or neither, is an error reported in the browser console, and nothing is mounted.

EmbedOptions

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

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
}

Every override applies to the pages shown in the frame. In a petition embed, the design fields style the petition and its follow-up campaign, and recipients and interpellations apply to the follow-up campaign once it opens.

Recipient resolution order

Recipients are resolved per interpellation with the following priority:

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

Design fields

Each design field replaces the campaign page's value from your Activoice admin (the campaign's own design when it has one, the organization's otherwise); an omitted field keeps it.

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 campaign page's value stays. A CSS that fails a check is dropped entirely, with a warning too.

Recipient

All fields are optional.

Events

Every analytics event the campaign or petition records is also posted to the host window as an ACTIVOICE_EVENT message, through postMessage, at the moment it happens. Listen for it to follow where visitors go and where they stop.

{
  "type": "ACTIVOICE_EVENT",
  "payload": {
    "event": "submit_questions",
    "campaignId": "a4e2b000-1234-4567-89ab-0123456789ab",
    "petitionId": null,
    "interpellationId": "7c1f3d2a-5b6e-4f8a-9c0d-1e2f3a4b5c6d",
    "sessionId": "3b9e8d7c-6f5a-4e3d-8c2b-1a0f9e8d7c6b",
    "medium": "email",
    "newsletterChoice": "subscribed",
    "customizationSkipped": false
  }
}

Every other property of an event is listed below. The order depends on the campaign: a geolocated campaign selects the recipient before its group, a single-channel campaign selects the channel automatically. The list grows with the product: ignore the events and properties you do not know.

automatic is true when the campaign made the selection on the visitor's behalf: a single recipient group, a single channel, a channel preset by the page. A selection is only reported when its value changes.

submit_questions is posted by the Generate button only when the form is valid, and by Do not use customization always, since that button validates nothing. newsletterChoice is the answer to the "keep me informed" checkbox:

The value records the choice submitted in the questions step, not a confirmed subscription: it is reported whether or not the CRM synchronization succeeds. A consent remembered from a previous campaign, petition, action, accepted CRM subscriber identity, or the My information dialog hides the box and reports already_subscribed; entering a different email address shows the box again.

confirm_sent records the visitor's confirmation, not verified delivery to the recipient. Reporting an issue, or answering that the action was not completed, does not post it. Loading the success page directly does not post it either.

Check both the source iframe and its origin before using a message. Register your listener before calling Activoice.init():

window.addEventListener('message', (event) => {
  const iframe = document.querySelector('#av-embed-container iframe')
  if (
    iframe &&
    event.source === iframe.contentWindow &&
    event.origin === new URL(iframe.src).origin &&
    event.data?.type === 'ACTIVOICE_EVENT'
  ) {
    const { event: name, campaignId, petitionId, sessionId, medium } =
      event.data.payload
    // Forward these values to your analytics integration.
    console.log({ name, campaignId, petitionId, sessionId, medium })
  }
})

TypeScript types

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

Then point your tsconfig.json to it:

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