Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vortexsoftware.com/llms.txt

Use this file to discover all available pages before exploring further.

Vortex offers two broad categories of events.
  • Events directly tied to user interaction on the invitation form itself. These events can be consumed via an onEvent function. This option is great if you would like to immediately react to something that happens on the invitation form without having to set up a webhook.
  • All other events related to your invitation flow, such as the sending of emails, clicks on invitation links, etc. These events will be consumed via webhook or direct feed into analytics services such as Segment, Mixpanel and Amplitude (COMING SOON!)
All events have the follow set of standard properties. Payload varies by event, as outlined in the sections for each individual event. 
type UUID = string & { _brand: 'UUID' };

type BaseEvent {
  organizationId: UUID; // id of the organization for which the event falls under
  accountId: UUID; // the id of the specific account within the organization for which the event falls under
  projectId: UUID; // the id of the specific project within the account for which the event falls under
  widgetConfigurationId: UUID; // the id of the widget configuration that originated the event or the underlying invitation associated with the event
  environmentId: UUID; // the id of the environment in which the event occurred
  deploymentId: UUID; // the id of the deployment specific to this event
  name: string; // the name of the event
  timestamp: Date; // the time which the event occurred
  platform: string; // the platform (web, ios, android) on which the invitation was initiated
  useragent?: string; // the useragent from of the device used to create the event if available
  referer?: string; // the full URL of the referer if available
  refererDomain?: string; // the domain of the referer if available.
  sessionId?: UUID; // the session id, generated by the widget, of a particular session.
  foreignUserId?: string; // the id, in your system, of the user that created the event, if available/applicable
  segmentation?: Record<string, any>; // segmentation of the event as specified by the widget prop
  payload?: Record<string, any>; // any unique information for the specific event type
  groups?: Array<{ // the group or groups that the event is related to as defined by your system
    type: string;
    id: string;
    name: string;
  }>; 
}

​
Invitation form events

These events are available via onEvent.

​
invite_formRender_succeeded

This event fires when the invitation form is rendered. 
type invite_formRender_succeeded extends BaseEvent {
  payload?: null;
}

​
invite_formRender_failed

This event fires when there is an error trying to render the invite form. 
type invite_formRender_failed extends BaseEvent {
  payload?: {
    error: string; // the error message
  };
}

​
email_field_focussed

This event fires when the user puts focus on the form field to enter email addresses. 
type email_field_focussed extends BaseEvent {
  payload?: {
    timestamp: number // the number of MS since the form was rendered
  };
}

​
email_field_blurred

This event fires when the user blurs the email form field that was once in focus. 
type email_field_blurred extends BaseEvent {
  payload?: {
    timestamp: number // the number of MS since the form was rendered
  };
}

​
email_submission_validated

This event fires when an email address entered by the user is validated. The results of the validation are included, even when your own validation function was used. 
type email_submission_validated extends BaseEvent {
  payload?: {
    email: string;
    isValid: boolean;
  };
}

​
email_fieldSubmission_succeeded

This event fires when the user invites people via email by manually entering email addresses. 
type email_fieldSubmission_succeeded extends BaseEvent {
  payload?: {
    formData: Record<string, any>; // this is the raw form data that is being sent to create invitations
  };
}

​
email_fieldSubmission_failed

This event fires when the user clicks the main Invite/CTA button on your invite form and the Vortex backend responds with an error. 
type email_fieldSubmission_failed extends BaseEvent {
  payload?: {
    error: string; // the error message
  };
}

​
email_fieldSubmission_alreadyInvited

This event fires when the user tries to submit an email address for which an open invitation already exists.

​
email_fieldSubmission_alreadyMember

This event fires when the user tries to submit an email address that represent a user that is already a member.

​
sharingDestination_button_clicked

This event fires when the user clicks on any of the sharing options for shareable links provided on the invite form. 
type sharingDestination_button_clicked extends BaseEvent {
  payload?: {
    clickName: string; // the text of the copy share link element
  };
}

​
contactImport_button_clicked

This event fires when the user clicks on any of the buttons for inviting from a list of contacts (e.g., Google contacts, device contacts) provided on the invite form. 
type contactImport_button_clicked extends BaseEvent {
  payload?: {
    clickName: string; // the text of the copy share link element
  };
}

​
All other events

These events aren’t covered by onEvent, and are currently just listed here for reference.

​
autojoin_enabled

This event fires when autojoin is enabled via the checkbox on an inviation form. 
type sharingDestination_button_clicked extends BaseEvent {
  payload?: {
    domainsCount: string; // the number of domains allowed
  };
}

​
autojoin_disabled

This event fires when autojoin is disabled via the checkbox on an inviation form.

​
autojoin_configured

This event fires when allowed domains are added or removed, either via autojoin being enabled/disabled via the invitation form, or via API call. Note that platform will be set to “api” in the latter case. 
type sharingDestination_button_clicked extends BaseEvent {
  payload?: {
    totalDomains: string; // the totalnumber of domains allowed
    domainsAdded: string; // the number of domains added
    domainsRemoved: string; // the number of domains removed
  };
}

​
invitation_fingerprint_matched

Fires server-side on successful fingerprint matching, including OS name and OS version in the payload.

​
invitation_emailSend_succeeded

Fires when Vortex sends an invitation email. 
type invitation_emailSend_succeeded extends BaseEvent {
  payload?: {
    targets: { type: string; value: string }[]; // the invitation targets
    invitationId: UUID; // the invitation id associated with the event
  }
}

​
invitation_emailSend_failed

Fires when the sending of an invitation email fails. 
type invitation_emailSend_failed extends BaseEvent {
  payload?: {
    error: string; // The error that was encountered. For instance, if you initially verified your domain with vortex and suddenly removed or altered the DNS entries, you might see an error here like "Domain is not verified. The following identities failed the check: yourdomain.com"
    invitationId: UUID; // the invitation id associated with the event
  }
}

​
reminder_emailSend_succeeded

Fires when a reminder email is sent to an invitee. 
type reminder_emailSend_succeeded extends BaseEvent {
  payload?: {
    targets: { type: string; value: string }[]; // the invitation targets
    invitationId: UUID; // the invitation id associated with the event
  }
}

​
nudge_emailSend_succeeded

Fires when a nudge email is sent to an inviter. 
type nudge_emailSend_succeeded extends BaseEvent {
  payload?: {
    targets: { type: string; value: string }[]; // the invitation targets
    invitationId: UUID; // the invitation id associated with the event
  }
}

​
acceptance_emailSend_succeeded

Fires when an acceptance notification email is sent to an inviter.

​
acceptance_emailSend_failed

Fires when the sending of an acceptance notification email fails.

​
email_opened

Fires when an invitation or reminder email is opened.

​
email_bounced

Fires when an email bounces.

​
email_reported

Fires when an email is reported as spam. Fires when an invitee clicks on an invitation link. 
type invitation_link_clicked extends BaseEvent {
  payload?: {
    targets: { type: string; value: string }[]; // the invitation targets
    invitationId: UUID; // the invitation id associated with the event
  }
}

​
invitation_created

Fires when an invitation of any type is created. 
type invitation_created extends BaseEvent {
  payload?: {
    type: string; // single-use or multi-use
    source: string; // email, phone, share, internal, or autojoin
    invitationId: UUID; // the invitation id associated with the event
  }
}

​
invitation_accepted

Fires when an invitation is marked as accepted on the Vortex backend. 
type invitation_accepted extends BaseEvent {
  payload?: {
    targets: { type: string; value: string }[]; // the actual target that accepted the invitation (may differ from specified target)
    invitationId: UUID; // the invitation id associated with the event
  }
}
Fires when Vortex detects that a shareable link has been shared. This is based on automated requests that services make to fetch rich content for rendering the link. Note that unfurls are only supported for specific services, and this event should not be considered a highly accurate count of the number of people that have seen the invitation link. This is especially true when links are shared in group settings, like a multi-person SMS or a Slack channel. 
type invitation_link_unfurled extends BaseEvent {
  payload?: {
    invitationId: UUID; // the id of the shareable link
  };
}