Global Form Events – Salesmate

When you embed a Salesmate webform on your website, the form runs inside an iframe. Global Form Events allow your webpage to respond to events from the form, such as when the form is ready, successfully submitted, or when a submission fails. You can also use these events to read and update field values from outside the iframe.

Requirements

Global form events work only with forms added using the embed code.
A manually added <iframe> can display the form, but it does not trigger global form events and its field values cannot be accessed or modified.

Form Events

Salesmate webforms emit events during their lifecycle. You can listen for these events using window.addEventListener().

Event	Description
`sm-form-event:on-ready`	The form has finished loading and rendering. Its fields can now be read and updated.
`sm-form-event:on-submission:success`	The form was submitted successfully.
`sm-form-event:on-submission:failed`	The form submission was rejected.

For example:

window.addEventListener('sm-form-event:on-ready', (event) => {
  console.log('A form is ready', event.detail);
});

Important: Register your event listeners before the Salesmate embed snippet.

The on-ready event is triggered as soon as the form finishes rendering. If the listener is registered after the embed snippet, the event may already have fired and will be missed. Add your listener in the <head> or anywhere before the embed snippet.

Event Object

Every global form event contains a detail object with information about the form that triggered the event.

window.addEventListener('sm-form-event:on-ready', (event) => {
  const { formId, instanceId } = event.detail;
});

The event object includes the following properties:

formId: The ID of the form. Multiple copies of the same form on a page have the same formId.
instanceId: A unique ID for each embedded form instance. Use this to distinguish between multiple copies of the same form.
message: The error message. Available for on-submission:failed and on-command:failed.
method: The method that failed, such as setFieldValue. Available for on-command:failed.

To work with the form that triggered an event, pass the event to getFormFromEvent():

window.addEventListener('sm-form-event:on-ready', (event) => {
  const form = SalesmateFormsV1.getFormFromEvent(event);
  form.setFieldValue('Contact.email','user@example.com');
});

Getting Form Instances

The SalesmateFormsV1 global is available on any webpage where the Salesmate embed snippet is loaded.

getForms

Use getForms() to retrieve all form instances on the page that have completed loading.

Forms that are still loading are not included.

const forms = SalesmateFormsV1.getForms();
console.log(`${forms.length} form(s) ready`);

getFormFromEvent

Use getFormFromEvent() to retrieve the specific form instance that triggered an event.

window.addEventListener('sm-form-event:on-submission:success', (event) => {
  const form = SalesmateFormsV1.getFormFromEvent(event);
  console.log('Submitted:', form.formName);
});

Field Names

Salesmate form fields use the following naming format:

Module.fieldName

For example:

Contact.email
Contact.firstName
Company.name
CustomQuestions.how_did_you_hear

You can also use a field's bare name, such as email, when only one module on the form contains a field with that name.

If the same field name exists in multiple modules, the bare field name is considered ambiguous and the qualified field name must be used.

For example:

'name' is ambiguous on this form — use one of: Contact.name, Company.name

Use getFormFieldValues() to identify the exact field names accepted by the form.

Form Instance Methods

All form instance methods are synchronous. You can call them on a form instance returned by getForms() or getFormFromEvent().

getFormId

Returns the ID of the form as a string.

form.getFormId();

You can also access the same value through the formId property:

form.formId;

getInstanceId

Returns the unique ID of the specific embedded form instance.

Two copies of the same form have the same formId but different instanceId values.

form.getInstanceId();

You can also access it through:

form.instanceId;

getFormName

Returns the form name configured in Salesmate.

form.getFormName();

You can also access it through:

form.formName;

getFormFieldValues

Returns all fields available on the form, including hidden fields.

form.getFormFieldValues();

The method returns an array containing the field name, current value, and whether the field is hidden.

Example:

[
  {
    "name": "Contact.firstName",
    "value": "Ada",
    "isHidden": false
  },
  {
    "name": "Contact.email",
    "value": "ada@example.com",
    "isHidden": false
  },
  {
    "name": "Contact.utmSource",
    "value": "newsletter",
    "isHidden": true
  }
]

The returned array is a copy. Modifying it does not modify the form. Use setFieldValue() to update a field.

getFieldValue

Returns the current value of a specific field.

form.getFieldValue('Contact.email');

If the field does not exist on the form, the method returns undefined.

getRedirectUrl

Returns the URL where the visitor will be redirected after a successful form submission.

If the form displays a success message instead of redirecting, the method returns null.

This method is meaningful when used after the on-submission:success event.

window.addEventListener('sm-form-event:on-submission:success', (event) => {
  const form = SalesmateFormsV1.getFormFromEvent(event);
  const url = form.getRedirectUrl();

  if (url) {
    console.log('Redirecting to', url);
  }
});

setFieldValue

Use setFieldValue() to set or update a field's value programmatically.

It works with both visible and hidden fields.

window.addEventListener('sm-form-event:on-ready', (event) => {
  const form = SalesmateFormsV1.getFormFromEvent(event);

  form.setFieldValue('Contact.email', 'ada@example.com');
  form.setFieldValue('Contact.utmSource', 'spring-campaign');
});

Important:

setFieldValue() does not throw an error and does not return a value.
The request is delivered to the form asynchronously.
If the field name is invalid, the failure is reported through an on-command:failed event and logged in the browser console.
Use getFieldValue() if you need to verify that the value was applied.
Call setFieldValue() on or after the on-ready event.

Supported Value Conversion

Salesmate automatically converts values for certain field types:

Boolean: Accepts a boolean or "true" / "false" string.
MultiSelect: Accepts an array of strings or a comma-separated string.
Date: Accepts a value in YYYY-MM-DD format.
DateTime / IndividualDateTime: Accepts a value in YYYY-MM-DD hh:mm A format.

Other field types, such as Text, Textarea, Email, Phone, URL, Number, Currency, Decimal, Select, Radio, and Checkbox, are set using the value provided.

For Select and Radio fields, the value must match one of the field's configured options.

Hidden fields are not converted. Their values are stored and submitted exactly as provided.

Hidden Fields

Hidden fields do not appear on the form but are submitted along with the form.

Their values are resolved in the following order:

A value set using setFieldValue().
A matching query parameter in the page URL, including UTM parameters.
The field's default value configured in Salesmate.

Hidden fields are returned by getFormFieldValues() with isHidden: true and can be read and updated in the same way as visible fields.

Working with Multiple Forms

The formId is not unique on a webpage. If the same form is embedded multiple times, each copy has the same formId but a different instanceId.

Always use instanceId to distinguish between multiple instances.

For event-based interactions, use getFormFromEvent() rather than assuming the first form returned by getForms() is the form you want to modify.