JavaScript events (analytics & GTM)

OctaForms fires browser events you can listen for to measure how visitors use your forms and the callback widget. This is the one page to hand to whoever sets up your analytics or Google Tag Manager.

Every event name starts with octaforms:. There are two kinds.

The analytics events (listen on document)

These are the events you want for tracking. They bubble up to document, so one listener catches all of them, and they fire for every OctaForms form on the page. Not just the callback widget.

Each event carries a detail object with extra data.

Event	Fires when	detail
octaforms:form-start	A visitor first interacts with a form field	slug, location
octaforms:form-success	A form is submitted successfully	slug, location
octaforms:form-error	A submit is rejected (validation, rate limit, etc.)	slug, location, status
octaforms:widget-open	The callback widget popup opens	location, mode
octaforms:tab-switch	The visitor switches a tab in the widget	location, tab
octaforms:phone-call	The visitor taps the phone number in the widget	location, phone, trigger
octaforms:phone-copy	The visitor copies the phone number	location, phone, success

What the detail fields mean:

• slug identifies which form it was (for example contact, callback, message). This is the reliable way to tell forms apart.
• location is a human-readable label for where the form sits. It comes from the optional data-octa-forms-context on the form. For the callback widget it is always Widget callback. When no label is set it falls back to the slug.
• status is the HTTP status of a failed submit (for example 400 for a validation error, 429 when rate-limited).
• mode / tab is which widget tab is active (phone, callback or message).
• phone is the number, trigger is how the call started, success is whether the copy worked.

Send everything to Google Tag Manager

Drop this once on your site (or as a Custom HTML tag in GTM). It forwards every OctaForms event into the dataLayer, where you can build triggers on event equal to octaforms:form-success and so on.

<script>
[
  'form-start',
  'form-success',
  'form-error',
  'widget-open',
  'tab-switch',
  'phone-call',
  'phone-copy',
].forEach(function (name) {
  document.addEventListener('octaforms:' + name, function (e) {
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push(
      Object.assign({ event: 'octaforms:' + name }, e.detail)
    );
  });
});
</script>

A single conversion trigger in GTM is then event equals octaforms:form-success. Use the slug variable if you want to count only one form.

The raw form events (on the form element)

If you write your own theme JavaScript and want the full server response, the helper also fires two events on the <form> element itself (these do not bubble as analytics events):

form.addEventListener('octaforms:success', (e) => {
  // e.detail is the full submission result from the server
});
form.addEventListener('octaforms:error', (e) => {
  // e.detail is { status, errors }
});

Use octaforms:form-success / octaforms:form-error on document for analytics, and these two on the form only when you need the raw payload. See The JS helper.

Good to know

• The analytics events fire whether a form was placed with the shortcode, rendered by your theme, or shown in the callback widget.
• octaforms:form-start fires once per form, on the first real interaction. A synthetic focus the widget uses internally does not trigger it.
• These events are for measurement. They do not change what the form does, and turning off analytics does not affect submissions.