1. Sign in

API documentation

Table of contents

  1. Introduction
  2. Libraries
  3. Sending to people
  4. Listing survey responses
  5. Getting metrics
  6. Adding survey responses
  7. Deleting pending survey requests
  8. Unsubscribing people
  9. Listing people
  10. Listing unsubscribed people
  11. Listing bounced people
  12. Deleting people
  13. Getting Autopilot configuration
  14. Listing people in Autopilot
  15. Adding people to Autopilot
  16. Removing people from Autopilot
  17. Webhooks
  18. Web snippet

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): 2024-12-03T17:24:09Z.

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?”. Check out our help page for more information on this special property.

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.

You can optionally configure the thank you page with a custom message and link. For example, pass { thank_you_message: "message" } which will display in the thank you page, once the survey has been completed. You can also pass { thank_you_link_text: "text", thank_you_link_url: "url" } to configure the link displayed on the thank you page. Check out our help page for more information on these special properties.

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.

forceDisplay Boolean

When true, skips checks we perform to avoid over-surveying.

Note: survey throttling is always considered.

minTimeOnPage Number The number of seconds to wait after the page has loaded before showing a survey. (Default: two seconds)
minTimeForDisplay Number

The number of seconds to try surveying a person. (Default: two minutes)

When a person chooses not to immediately respond we will re-display the survey for a period of time. Please note that the survey will not be re-displayed when it is explicitly closed by a person.

onShow Function

A callback invoked when a survey is presented to a person.

onRespond Function

A callback that is invoked immediately after a person selects a score.

Note: the score is not provided to the callback.

onComment Function

A callback invoked after a person submits a comment. The callback is invoked regardless of whether a person leaves a comment.

Note: the comment is not provided to the callback.

onHide Function

A callback that is invoked when the survey is closed. This will be triggered by a person explicitly closing the survey or when the survey auto-closes.

darkBackground Boolean

By default, the Additional Questions modal popup will have a light white background. You can pass darkBackground: true to switch to a darker background. This will not affect the survey appearance until the Additional Questions modal pops up.

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 will automatically take care of sampling to optimize the rate of feedback throughout your billing period. This is based on a number of factors, including your current plan, your visitor traffic and survey throttling.

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().

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.

Multiple projects

You can place snippets from different projects on the same page. We will ensure that only one survey is shown at a time. A person’s eligibility to be surveyed is based on the project and person. In other words, your projects are completely independent.

Cookies

Our web snippet stores a cookie named _delighted_web containing a few timestamps and identifiers. This helps us re-display a survey on other pages if the person chose not to respond when it was first presented. It also helps avoid unnecessary work and calls to Delighted when a person has been recently surveyed.