API documentation

Web snippet

Survey visitors directly on your site with a simple code snippet.

Getting started

  1. Go to the Web platform page and follow the steps to configure and activate your snippet.
  2. Copy and paste the snippet provided into your site.
  3. That’s it!

In most cases, that is all you will need to do. However, the Delighted web snippet is very powerful and fully configurable. For advanced usage, read on.

Advanced usage

We provide several presets in the Web integration interface and you can update configuration directly in Delighted, without needing to modify any code. The configuration you set in Delighted provides the defaults only – you can customize in the call to delighted.survey().

Full API reference

The API has a single function, delighted.survey(). You should call this whenever you want to the snippet to consider showing a survey to the current visitor. Below is a full list of the options you can specify:

Name Type Description
email String Email of the person being surveyed.
name String Name of the person being surveyed.
createdAt String

The time when the person to survey was created. This value will be considered when showing the initial survey.

This should be in ISO8601 format. Formatting example (for the current time): 2018-12-10T11:14:24Z.

properties Object

Custom properties to associate with the survey. You can add as many properties as you need.

For example, if you wanted to add a “Customer ID” and a “Location”, you would set this value to, { customerId: 123, location: USA }.

You can optionally set a custom Question Product Name to be used in the survey question. For example, our fictitious clothing company, Hem & Stitch, could pass { questionProductName: "The Classic Oxford" } which would result in the following question being shown in the survey: “How likely are you to recommend The Classic Oxford to a friend?”.

You can optionally set a specific Locale to be used in the survey experience. This will determine localization (including language) of the survey experience. This locale string is composed of a lowercase ISO 639-1 language code and an optional uppercase ISO 3166-1 alpha-2 country code, separated by a hyphen. For example, to specify German, pass { locale: "de" }, or to specify Chinese (Simplified), pass { locale: "zh-CN" }.

We currently support the following locales: ar/Arabic, bg/Bulgarian, zh-CN/Chinese (Simplified), zh-HK/Chinese (Traditional, Hong Kong), zh-TW/Chinese (Traditional, Taiwan), hr/Croatian, cs/Czech, da/Danish, nl/Dutch, en/English, et/Estonian, fi/Finnish, fr/French, ka/Georgian, de/German, el/Greek, he/Hebrew, hu/Hungarian, id/Indonesian, it/Italian, ja/Japanese, ko/Korean, lv/Latvian, lt/Lithuanian, ms/Malaysian, nb/Norwegian Bokmål, pl/Polish, pt-BR/Portuguese (Brazil), pt/Portuguese (Portugal), ro/Romanian, ru/Russian, sr/Serbian, es/Spanish, sv/Swedish, th/Thai, tr/Turkish, and vi/Vietnamese. If you pass a value which is not in this list, the default en/English locale will be used. Please get in touch with us if you would like us to add a locale.

initialDelay Number

The number of seconds to wait before showing a person their initial survey. Useful in cases where you want visitors to have been to your site at least some amount of time before they would be eligible to be surveyed. If you pass createdAt, that value will be used as the starting point.

If you want to show a survey as soon as possible, set this value to 0. There is no maximum delay.

Note: survey throttling is always considered.

recurringPeriod Number

The number of seconds to wait before showing recurring surveys, after the initial one. Useful if you want the same person to be asked for feedback again.

If you pass null or false, recurring surveys will disabled. There is no maximum period.

Note: survey throttling is always considered.

Test mode

You can force the survey to show in your browser by simple appending ?delighted=test to the URL where you have included the snippet. This special mode will show you the survey every time you call delighted.survey(), regardless of the options you pass, and overrides throttling and Adaptive Sampling. This only affects your own view of the page and survey.

Adaptive Sampling

We automatically take care of sampling to optimize the rate of feedback. This is based on a number of factors, including your current plan and site traffic.

As we learn more about the traffic to your site, the sampling rate will update in real time, ensuring you receive an steady stream of feedback throughout the entire month. This makes it easier to track changes over time, and also helps to ensure the feedback is unbiased.

Note: If you are in test mode, the sampling mechanism will be bypassed, and the survey will be shown every time. This makes it easier for you to test.

Survey throttling

Before we show someone a survey, we will make sure they have not already received a survey from you within the time period you specify. Throttling works across web and email, if you pass us an email address when calling delighted.survey().

You can change your account-level throttling here.

Note: If you are in test mode, the throttling mechanism will be bypassed, and the survey will be shown every time. This makes it easier for you to test.