Website inline form API


This is a technical documentation of the API

For more user-case oriented examples see Website inline form: API examples.


window.onUsersnapLoad = function(widgetApi) {
  widgetApi.init({ mountNode: document.getElementById('widgetContainer') });
var script = document.createElement('script');
script.defer = 1;
script.src = '<<PROJECT_API_KEY>>?onload=onUsersnapLoad';

API object

interface GlobalApi {
  init: (options: InitOptions) => void,
  on: (eventName: string, callback: (event: any) => void) => void,
  off: (eventName: string, callback: (event: any) => void) => void,


  mountNode: document.getElementById('widgetContainer')
  locale: 'de',

The init function initializes the global api. It must be called before calling any other api method.


  • options
  • options.mountNode – The container element in which the widget should appear
  • options.locale: string – Language in which widgets should be displayed
  • options.useSystemFonts: boolean – Can be used to disable loading external fonts. Defaults to false
  • options.useLocalStorage: boolean – Can be used to disable usage of localStorage. Defaults to true
  • options.nativeScreenshot: boolean – Can be used to enable the usage of the native screenshot feature. Defaults to false
  • options.collectGeoLocation: 'all' | 'none' – can be used to disable the collection of IP and geo location. Defaults to 'all'

Returns Promise<void>


function handleSubmit() {
  console.log('Widget was submitted')
}'submit', handleSubmit)

Registers an event handler for widget events.
For a detailed list of available events and how they can be used see section Widget Events


  • eventName: string – the name of the widget event you want to listen to
  • callback: (event: WidgetEvent) => void – callback to handle the event. The structure of the received object depends on the event.

Returns void

off()'submit', handleSubmit)

Removes an event handler


  • eventName: string – the name of the widget event want to remove the listener from
  • callback: (event: WidgetEvent) => void – same callback that was used for registering the event

Returns void

Widget Events

  • open – A widget was opened.
  • beforeSubmit– Before form values are submitted
  • submit – After form values were submitted

open event

type ValueKey = 'assignee' | 'custom' | 'labels' | 'visitor'

interface OpenEvent {
  apiKey: string,
  api: {
    setValue: (key: ValueKey, value: any) => void,
  • apiKey– API key of the widget that was opened
  • api.setValue – method to set form values


function handleWidgetOpened(event) {
  // You can check whether a specific widget was called
  if (event.apiKey !== '<PROJECT_API_KEY>') return;
  // Set Assignee. A User with this email has to exist in your Usersnap account
  event.api.setValue('assignee', '[email protected]') 
  // Set custom data
  event.api.setValue('custom', { applicationLanguage : 'de' })
  // Set labels
  event.api.setValue('labels', ['bug', 'critical'])
  // Set email
  event.api.setValue('visitor', '[email protected]')
api.on('open', handleWidgetOpened)

beforeSubmit event

type ValueKey = 'assignee' | 'custom' | 'labels' | 'visitor'

interface BeforeSubmitEvent {
  apiKey: string,
  api: {
    setValue (key: ValueKey, value: any) => void,
  values: {
    assignee?: string,
    custom?: any,
  	labels?: string,
    visitor: string,
  • apiKey– API key of the widget that will be submitted
  • api.setValue – method to set form values. Allows changing values before they are submitted.
  • values – values that will be submitted


function handleBeforeSubmit(event) {
  var labels = event.values.labels
  if (labels && labels.includes('bug')) {
  	event.api.setValue('assignee', '[email protected]')
api.on('beforeSubmit', handleBeforeSubmit)

submit event

interface CloseEvent {
  apiKey: string,
  • apiKey– API key of the widget that was submitted


function handleSubmit() {
  // do something
api.on('submit', handleSubmit)