. Example: footer | #mydivid
fblytag("position", "top"); //optional: top | inside
```
# Attaching custom metadata to responses
## Overview
Custom metadata is any additional information you wish to include in your response. This metadata will be available in the Response list in the analytics section in Feedbackly. You can also filter and group responses by metadata.
Metadata will be included to the subsequent survey responses made by the visitor on the site. Metadata will always be included in responses until it is cleared or the user resets their browser cookies.
Note: Metadata can be added at any point of time **before** a survey is launched.
### Using the Javascript API to include metadata to the response
When the Feedbackly widget is installed on the site, run
```
FBLY.action("addMeta", KEY, VALUE);
```
Example:
`FBLY.action("addMeta", "customerId", "12345");`
This command adds a customer id to the subsequent responses of the user.
### Removing a single metadata value from the visitor
This action will a single metadata key and value from the visitor. It does not affect previous responses given by the user, however.
```
FBLY.action("removeMeta", KEY)
```
Example:
`FBLY.action("removeMeta", "customerId")`
This action removes the customerId set in the previous example.
### Clearing all metadata from a visitor
This action will clear all the metadata from the visitor. It does not affect previous responses given by the user, however. This action needs to be run before a survey is launched.
Using Javascript, run
```
FBLY.action("clearMeta")
```
# Triggering surveys via custom properties
### Overview
Custom triggering properties are used to have a more fine-grained control over the triggering properties of a Feedbackly website widget.
For instance, you might want to trigger a survey based on whether a customer is logged in to the members' are in your website. This can be easily accomplished provided that there is Javascript access to the information required to set the triggering behavior.
### Set up custom triggering parameters in the Feedbackly dashboard
In the website triggering options, open up *Advanced targeting* and add the property under *Custom Properties* like so
### Adding a custom triggering property to the Feedback widget via the Javascript API
When the Feedbackly widget is installed, run
```
FBLY.action("addCustomProperty", KEY, VALUE)
```
**Example**
Let's assume the information of the logged in status is stored in a Javascript variable accessible in the namespace the widget command is run. For this example, we'll assume it's stored in `user.loggedIn` variable.
Running `FBLY.action("addCustomProperty", "loggedIn", "true")` will tell the widget that the user is logged in. If the widget triggering settings has that property set, the survey will then trigger (if no other restrictions are set)
### Removing a single custom triggering property
When you want to prevent further surveys from displaying because of a custom property
When the Feedbackly widget is installed, run
```
FBLY.action("removeCustomProperty", KEY)
```
**Example**
Following the previous example, if we want to remove a custom triggering property (let's say the user logs out) we would run this command:
`FBLY.action("removeCustomProperty", "loggedIn")`
### Clearing all custom properties
This command clears all custom triggering properties of the visitor
```
FBLY.action("clearCustomProperties")
```
# Widget Hooks
#### On Survey Loaded
This action will trigger the given callback function when the survey is loaded and shown.
```javascript
FBLY.action("onSurveyLoaded", () => { /* Your code */})
```
#### On Response
This action will trigger the given callback function immediately after a customer answers a question of the survey. This means, if the survey has 3 questions the function will be called each time a question in answered, in this case 3 times. \
\
The response object will be passed as the first argument of the function. Available fields include:
| | |
| ------------ | -------------------------------- |
| surveyId | 12 byte ObjectId |
| questionId | 12 byte ObjectId |
| touchpointId | 12 byte ObjectId |
| language | string (ISO 639-1 language code) |
| data | varies |
```javascript
FBLY.action("onResponse", (r) => { /* Your code */})
```
#### On Survey Finished
This action will trigger the given callback function after the survey is completed.
```javascript
FBLY.action("onSurveyFinished", () => { /* Your code */})
```
#### on Survey Close
This action will trigger the given callback function if the survey closes either by user or programmatically. "isDeclined" flag is true only if the user closed the survey or if `FBLY.close(userDeclined)` called with userDeclined = true
```javascript
FBLY.action("onClose", (isDeclined) => { /* Your code */})
```
# Setting the language
If you need to change the language of the survey programmatically, you can achieve this using the provided JavaScript action along with the desired language code.
```
window.FBLY.action("setLanguage", "fi");
```
# Debugging website widgets
Due to the amount of variables it's not always straightforward to figure out why exactly a survey triggers/doesn't open for a visitor.
To find out more about the underlying reasons, Feedbackly provides the means to debug this.
If you need to check the installation status of a widget, please see [Verifying installation.](/website-widgets/getting-started#verifying-installation)
### List all triggering options available to the visitor
When on your website and with Feedbackly widget installed, open up the dev tools for the browser. In Chrome, this can be done via the command `⌘ + option + J`
Run the following command:
```
FBLY.getConfiguration();
```
The console should print out an array of configuration objects similar to this:
This is in essence the JSON-representation of your website triggering parameters available on the Feedbackly UI's widget triggering parameters. All the objects in this array are the potential surveys to be shown to the user when conditions are met.
### Listing client data
To find out what data the widget has recorded of the visitor, run
```
FBLY.getClientData();
```
This data can be useful in determining whether the visitor has met the conditions for a survey to be triggered.
A few remarks on the properties:
* `session.declinedActivations` lists whether the user has declined a survey, its id and timestamp
* `session.sampledActivations` shows whether the visitor fits to the sample of the survey
* `visitedUrls` shows all visited urls of the visitor
* `scroll` shows the current page scroll of the visitor
## Automatic debugging mode
To see loading information and created objects in a browser console, enable automatic debug mode by adding this to the end of your page URL (can also be set as a URL parameter):
```
#debug=true
```
or edit the original script tag to add following configuration for dev/test sites:
```
fblytag('debug', 'true');
```
# Response Webhooks
Getting Responses in real time to your endpoint
Response webhooks provide a way for responses to be delivered to an external web server. Webhook triggered immediately when a response saved. Note that Survey UI 3.0 in touchpoint settings must be enabled to use this feature.
#### Configuration
You can specify a URL in touchpoint settings by adding a custom settings with key "webhookURL". And if you want to attach an Authorization header to the request, you can add another custom settings with key "webhookAuthHeader" by the value being Authorization header itself.
#### Data
Webhook request body includes following fields;
| Field | Type | Example | Description |
|---|
| createdAt | string | "2023-10-19T13:33:02.980Z" | Response Date in ISO 8601 format |
| feedbackId | string | "65312e12949a0d0508b71dae" | Id of the full response chain the response belongs to |
| language | string | "en" | Language code in two letter ISO 639-1 format |
| surveyId | string | "612615c51e9b5b00726f4cb4" | Survey's id |
| surveyName | string | "My Survey" | Survey's name |
| touchpointId | string | "643186eaabea9200298eeb43" | Touchpoint's id |
| touchpointName | string | "My Touchpoint" | Touchpoint name |
| questionId | string | "612615c51e9b5b00726f4cb1" | Question's id |
| questionType | "Button" | "NPS" | "Word" | "Slider" | "Contact" | "Text" | "Image" | "NPS" | Question type |
| questionTitle | string | "How likely are you to recommend us to your friends and colleagues?" | The title of the question in the response's language |
| tags | string[] | ["CSAT"] | Question tags that set in the survey editor |
| answer | string | string[] | number | 5, "Apple", ["Apple", "Orange"] | Mixed-type field related to question type |
| browser | string | "Chrome 118.0.0.0" | Respondent's Browser |
| device | string | "Macintosh" | Respondent's Device |
| os | string | "Mac OS 10.15.7" | Respondent's OS |
| metadata | object | { "key": "value" } | metadata attached to response |
| cluster | string? | "detractor" | NPS or EVI cluster of the response |
| fieldId | string? | "507f1f77bcf86cd799439013" | Field id (used in Contact and Slider question types) |
| fieldName | string? | "Email" | Field name (used in Contact and Slider) in the response's language |
| contactId | string? | "507f1f77bcf86cd799439013" | Contact Id if the survey responded from a email/sms campaign |
# Getting started
Feedbackly has a publicly available REST API to pull data from the Feedbackly software into other systems.
### Getting started
You must have the API enabled in order to proceed. The REST API is available on the Enterprise plan of Feedbackly. Contact Feedbackly support if you need access to the API.
## Creating an API key
When the Feedbackly API is available to your organization, you can create an API key from the Feedbackly dashboard under the User profile settings tab.
# Authentication
Feedbackly API requests are authenticated with an API key that can be retrieved from the user settings.
## Making requests
Requests are authenticated with the `Authorization` header. Example:
```
headers = {'Authorization': 'ey0iuefg.834xcunerun348efnsd'}
```
# Responses
Getting responses from Feedbackly
### Response data object
| Field | Type | Example | Description |
| --------------- | ------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------ |
| touchpointName | string | Touchpoint 1 | Touch point name |
| answer | string \| string\[] \| number | 0.5, "Apple", \["Apple", "Orange"] | Mixed-type field related to question type |
| questionType | "Button" \| "NPS" \| "Word" \| "Slider" \| "Contact" \| "Text" \| "Image" | "Button" | [Question type](/v.5.0.2/api/notes#question-types) |
| metadata | { \[key: string]: string} | {phone: "iPhone X"} | metadata attached to response |
| fieldId? | string | "507f1f77bcf86cd799439013" | Field id (used in Contact and Slider question types) |
| valueString? | string | "Orange" | String value of the response |
| valueArray? | string\[] | \["aoudfsa", "sidfvcx"] | The technical id of the given responses (Word/Image) |
| valueNum | number | 0.5 | Number value of the response |
| responseChainId | string | "507f1f77bcf86cd799439013" | Id of the full response chain the response belongs to |
| questionId | string | "507f1f77bcf86cd799439013" | Question's id |
| question | string | "How did we succeed today?" | The title of the question in the preferred language (if available) |
| teamId | string | "507f1f77bcf86cd799439013" | Team's id |
| createdAtDate | string | "2017-03-27T09:03:59.133Z" | Response's date in Javascript format |
| createdAt | number | 1490605439 | Response's date in UNIX timestamp |
| touchpointId | string | "507f1f77bcf86cd799439013" | Touchpoint's id |
| \_id | string | "507f1f77bcf86cd799439013" | id of the response |
| language | string | "en" | language the response is given in |
| teamName | string | "My team" | Team's name |
| fieldName | string | "Email" | Field name (used in Contact and Slider) |
| tags | string\[] | \["CSAT"] | Question tags set in the survey editor |
| browser | string | Mac OS X Chrome 84.0.4147.105 | Browser information |
# GET Responses
## Get Responses
`GET` `https://api.feedbackly.com/v5.0.2/responses`
This endpoint allows you to access Responses objects from Feedbackly. \
For clarification on different outputs by question type, take a look at the Question types note
#### Query Parameters
| Name | Type | Description |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------ |
| skip | number | Number of documents to skip from the start |
| metadata | string | Filters with provided metadata key-value pairs. Separate with semicolon. Format maker:Apple;phone:iPhone |
| fieldId | string | Filters based on the provided field ids. Please refer to the docs about this id. |
| questionType | string | Array of question types. See the docs for available question types. |
| questionId | string | Filter responses by given question id |
| surveyId | string | Filter responses by given survey ids |
| touchpointId | string | Filter responses by given touchpoint ids |
| createdTo | number | UNIX timestamp. Fetch responses from before this timestamp. Defaults to current timestamp if not specified. |
| preferredLanguage | string | Language to fetch question titles etc. Defaults to 'en' or the first language available. |
| createdFrom | number | UNIX timestamp. Fetch responses starting from this timestamp. Defaults to start of the day if not specified. |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| Authorization | string |
Authentication token to access the API eg:
'Authorization': 'ey0iuefg.834xcunerun348efnsd'
|
{% tabs %}
{% tab title="200 Response successfully retrieved." %}
```
{
"data": [
{
"touchpointName": "Retail location 1",
"answer": 0.75,
"questionType": "Button",
"metadata": {
"model": "Tesla"
},
"valueNum": 0.75,
"responseChainId": "507f1f77bcf86cd799439011",
"questionId": "507f1f77bcf86cd799439012",
"surveyId": "507f1f77bcf86cd799439011",
"question": "How did we succeed today?",
"teamId": "507f1f77bcf86cd799439013",
"createdAtDate": "2019-12-31T10:00:00.000Z",
"createdAt": 1573507477,
"touchpointId": "507f1f77bcf86cd799439011",
"_id": "507f1f77bcf86cd799439011",
"language": "fi",
"teamName": "My team name",
"tags": [
"CSAT"
],
"browser": "Mac OS X Chrome 84.0.4147.105",
},
{
"answer": 4,
"valueNum": 4,
"language": "en",
"questionType": "NPS",
"questionId": "58d8d547b8c71e000e3824fd",
"createdAt": 1490605439,
"createdAtDate": "2017-03-27T09:03:59.133Z",
"_id": "5dc57703b7c935069aef31c6",
"question": "How likely are you to recommend us to a friend or colleague?",
"metadata": {},
"responseChainId": "58d8d57d42f73c78c47e2d3d",
"teamId": "507f1f77bcf86cd799439013",
"teamName": "My team name",
"touchpointId": "589c16ad87ef9860199cab37",
"touchpointName": "Retail location 1",
"tags": [],
"browser": "Mac OS X Chrome 84.0.4147.105",
}
],
"paging": {
"next": "https://api.feedbackly.com/v5/responses?skip=200",
"previous": "https://api.feedbackly.com/v5/responses?skip=0"
}
}
```
{% endtab %}
{% endtabs %}
### Response type description
| Field name | Type | Example | Description |
| ---------- | --------------------------------------------------------------- | ------- | ----------------------------- |
| data | [Response data](/v.5.0.2/api/responses#response-data-object)\[] | | The array of response objects |
| paging | [Pagination](/v.5.0.2/api/notes/pagination) | | Pagination object |
# GET Response by id
## Get Response by id
`GET` `https://api.feedbackly.com/v5.0.2/responses/:id`
Returns a single response by id
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------- |
| id | string | Response id |
#### Query Parameters
| Name | Type | Description |
| ----------------- | ------ | --------------------------------------------------------------------------------------- |
| preferredLanguage | string | Language to fetch question titles etc. Defaults to 'en' or the first language available |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------------------------------------------------------------------------------------ |
| Authorization | string | Authentication token to access the API eg: 'Authorization': 'ey0iuefg.834xcunerun348efnsd' |
{% tabs %}
{% tab title="200 " %}
```
{
"answer": [
"Facebook",
"LinkedIn"
],
"valueArray": [
"adfunr4",
"dsfgt1w"
],
"language": "en",
"questionType": "Word",
"questionId": "58d8d548a4753d000e4665ec",
"createdAt": 1490868345,
"createdAtDate": "2017-03-30T10:05:45.781Z",
"_id": "5dc576ffb7c935069aeebd68",
"question": "Where did you hear from us?",
"metadata": {},
"responseChainId": "58dcd870dde9550aec15ef12",
"teamId": "5dc56d54b7c935069aefa9e3",
"teamName": "My team 2",
"touchpointId": "589c16ad87ef9860199cab37",
"touchpointName": "Retail location 2",
"surveyId": "507f1f77bcf86cd799439011",
"tags": []
}
```
{% endtab %}
{% endtabs %}
### Response type description
Returns [Response data](/v.5.0.2/api/responses#response-data-object)
# Response chains
Getting response chains from Feedbackly
### Response chain data object
| Field | Type | Example | Description |
| --------------- | ------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------ |
| touchpointName | string | Touchpoint 1 | Touch point name |
| responseChainId | string | "507f1f77bcf86cd799439013" | Id of the full response chain the response belongs to |
| teamId | string | "507f1f77bcf86cd799439013" | Team's id |
| metadata | { \[key: string]: string} | {phone: "iPhone X"} | metadata attached to response |
| createdAtDate | string | "2017-03-27T09:03:59.133Z" | Response's date in Javascript format |
| createdAt | number | 1490605439 | Response's date in UNIX timestamp |
| touchpointId | string | "507f1f77bcf86cd799439013" | Touchpoint's id |
| \_id | string | "507f1f77bcf86cd799439013" | id of the response |
| language | string | "en" | language the response is given in |
| teamName | string | "My team" | Team's name |
| data | array | | Responses within the response chain |
| browser | string | Mac OS X Chrome 84.0.4147.105 | Browser information |
| > answer | string \| string\[] \| number | 0.5, "Apple", \["Apple", "Orange"] | Mixed-type field related to question type |
| > questionType | "Button" \| "NPS" \| "Word" \| "Slider" \| "Contact" \| "Text" \| "Image" | "Button" | [Question type](/v.5.0.2/api/notes#question-types) |
| > fieldId? | string | "507f1f77bcf86cd799439013" | Field id (used in Contact and Slider question types) |
| > valueString? | string | "Orange" | String value of the response |
| > valueArray? | string\[] | \["aoudfsa", "sidfvcx"] | The technical id of the given responses (Word/Image) |
| > valueNum | number | 0.5 | Number value of the response |
| > questionId | string | "507f1f77bcf86cd799439013" | Question's id |
| > question | string | "How did we succeed today?" | The title of the question in the preferred language (if available) |
| > fieldName | string | "Email" | Field name (used in Contact and Slider) |
| > tags | string\[] | \["CSAT"] | Question tags set in the survey editor |
# GET Response-chains
## Response chains
`GET` `https://api.feedbackly.com/v5.0.2/response-chains`
Gets responses grouped by a single respondent.
#### Query Parameters
| Name | Type | Description |
| ----------------- | ------ | --------------------------------------------------- |
| skip | number | No. of documents to skip from the start |
| createdTo | string | Filter by unix timestamp, ending at given value |
| createdFrom | string | Filter by unix timestamp, starting from given value |
| touchpointId | string | Filter by touchpoint id |
| surveyId | string | Filter by survey ids |
| preferredLanguage | string | Preferred language to show the question titles in |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------- |
| Authorization | string |
Authentication token to access the API. eg:
'Authorization': 'ey0iuefg.834xcunerun348efnsd'
|
{% tabs %}
{% tab title="200 " %}
```
{
data: [
{
"_id": "5979be93d296f3dbf83fb056",
"surveyId": "59788132f870b600018d6dda",
"touchpointId": "59529fbef3774c0001a49708",
"touchpointName": "My touchpoint",
"createdAt": 1501150867,
"createdAtDate": "2017-07-27T10:21:07.619Z",
"teamId": "5dc56d54b7c935069aefa9e2",
"teamName": "My team name",
"metadata": {
"customerId": "34tNa31"
},
"language": "en",
"browser": "Mac OS X Chrome 84.0.4147.105",
"responses": [
{
"question": "How likely are you to recommend us to your friend or colleague?",
"answer": 2,
"valueNum": 2,
"language": "en",
"questionType": "NPS",
"questionId": "5978813ab9215744ea08e463",
"surveyId": "59788132f870b600018d6dda"
},
{
"question": "Could you specify what was bad in your experience?",
"answer": "Your office branch was unclean.",
"valueString": "Your office branch was unclean.",
"language": "en",
"questionType": "Text",
"questionId": "597881a4b9215744ea08e464",
"surveyId": "59788132f870b600018d6dda"
}
]
}
],
"paging": {
"next": "https://api.feedbackly.com/v5/response-chains?skip=200",
"previous": "https://api.feedbackly.com/v5/response-chains?skip=0"
}
}
```
{% endtab %}
{% endtabs %}
### Return type description
| Field | Type | Example | Description |
| ------ | ---------------------------------------------------------------------------------- | ------- | -------------------------------------- |
| data | [Response chain data](/v.5.0.2/api/response-chains#response-chain-data-object) \[] | | Response chain with embedded responses |
| paging | [Pagination](/v.5.0.2/api/notes/pagination) | | Pagination object |
# GET Response-chain by id
## Response chain by id
`GET` `https://api.feedbackly.com/v5.0.2/response-chains/:id`
Gets an individual response chain by id
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------------------ |
| id | string | Id of the response chain |
#### Query Parameters
| Name | Type | Description |
| ----------------- | ------ | ------------------------------------------------- |
| preferredLanguage | string | Preferred language to show the question titles in |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------------------------------------------------------------------------------------- |
| Authorization | string | Authentication token to access the API. eg: 'Authorization': 'ey0iuefg.834xcunerun348efnsd' |
{% tabs %}
{% tab title="200 " %}
```
{
"_id": "5979be93d296f3dbf83fb056",
"surveyId": "59788132f870b600018d6dda",
"touchpointId": "59529fbef3774c0001a49708",
"touchpointName": "My touchpoint",
"createdAt": 1501150867,
"createdAtDate": "2017-07-27T10:21:07.619Z",
"teamId": "5dc56d54b7c935069aefa9e2",
"teamName": "My team name",
"metadata": {
"customerId": "34tNa31"
},
"language": "en",
"responses": [
{
"question": "How likely are you to recommend us to your friend or colleague?",
"answer": 2,
"valueNum": 2,
"language": "en",
"questionType": "NPS",
"questionId": "5978813ab9215744ea08e463",
"surveyId": "59788132f870b600018d6dda"
},
{
"question": "Could you specify what was bad in your experience?",
"answer": "Your office branch was unclean.",
"valueString": "Your office branch was unclean.",
"language": "en",
"questionType": "Text",
"questionId": "597881a4b9215744ea08e464",
"surveyId": "59788132f870b600018d6dda"
}
]
}
```
{% endtab %}
{% tab title="400 " %}
```
{error: "Not a valid response id Error id : 1583413424996/E5ohOOdp."}
```
{% endtab %}
{% tab title="404 If the provided id is not found" %}
```
{error: "Not found"}
```
{% endtab %}
{% endtabs %}
### Return type description
Returns [Response-chain data](/v.5.0.2/api/response-chains)
# Questions
Getting questions from Feedbackly
### Question data object
| Field | Type | Example | Description |
| ------------- | --------- | ----------------------------- | ---------------------------------------------------------------- |
| choicesString | string\[] | \["Lamb", "Beef", "Pork"] | List of available choices in the preferred language (Word/Image) |
| title | string | "Which meat did you buy?" | Question title in the preferred language |
| questionType | string | "Button" | See [question types](/v.5.0.2/api/notes#question-types) |
| \_id | string | "59b8de18784d2f0001a1590d" | Question id |
| languages | string\[] | \["en", "es"] | List of available languages for the question |
| language | string | "en" | The language currently selected to display titles etc |
| subtitle? | string | "Please select from below" | A subtitle for the question (if specified) |
| choices | array | | Array of possible choices |
| > fieldId | string | "1" | The id of the field |
| > fieldName | string | "Beef" | The label of the choice |
| > type? | string | "string" | Type of field (Contact question type) |
| > subType? | string | "phone" | Subtype of the field (Contact question type) |
| > imageUrl? | string | "
" | Image url of the choice (Image question type) |
# GET Questions
## Questions
`GET` `https://api.feedbackly.com/v5.0.2/questions`
This endpoint returns the questions of all surveys accessable from your account
#### Query Parameters
| Name | Type | Description |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| skip | number | Number of documents to skip from the start |
| preferredLanguage | string | Preferred language to show the question titles in eg. 'en'. If the specified language is not available, it will default to the first available language |
| questionId | array | Filter by question ids |
| surveyId | array | Survey ids related to the question |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| Authorization | string | Authentication token to access the API eg:
'Authorization': 'ey0iuefg.834xcunerun348efnsd'
|
{% tabs %}
{% tab title="200 " %}
```
{
"data": [
{
"_id": "59b8de984084087cd3346743",
"title": "Which meat did you buy?",
"choicesString": [
"Lamb",
"Beef",
"Pork"
],
"questionType": "Word",
"languages": [
"en"
],
"language": "en",
"choices": [
{
"fieldId": "1",
"fieldName": "Lamb"
},
{
"fieldId": "59b8deaa4084087cd3346744",
"fieldName": "Beef"
},
{
"fieldId": "59b8deac4084087cd3346745",
"fieldName": "Pork"
}
],
"surveyId": "59b8de18784d2f0001a1590d"
},
],
"paging": {
"next": "https://api.feedbackly.com/v5/questions?preferredLanguage=en&skip=100",
"previous": null
}
}
```
{% endtab %}
{% endtabs %}
### Request Return type
| Field | Type | Example | Description |
| ------ | ----------------------------------------------------------------------- | ------- | ----------------- |
| data | [Question Data object](/v.5.0.2/api/questions#question-data-object) \[] | | Question objects |
| paging | [Pagination](/v.5.0.2/api/notes#pagination) | | Pagination object |
# GET Question by id
## Question by id
`GET` `https://api.feedbackly.com/v5.0.2/questions/:id`
Gets a specific question by id
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------- |
| id | string | Question id |
#### Query Parameters
| Name | Type | Description |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| preferredLanguage | string | Preferred language to show the question titles in eg. 'en'. If the specified language is not available, it will default to the first available language |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------------------------------------------------------------------------------------ |
| Authorization | string | Authentication token to access the API eg: 'Authorization': 'ey0iuefg.834xcunerun348efnsd' |
{% tabs %}
{% tab title="200 " %}
```
{
"_id": "58d8d547b8c71e000e3824fc",
"title": "How likely are you to recommend us to a friend or colleague?",
"subtitle": "0=Not likely at all 10=Extremely likely",
"choicesString": [],
"questionType": "NPS",
"languages": [
"en",
"es",
"af"
],
"language": "en",
"choices": [],
"surveyId": "58d8d3d14cb016000e203e0e"
}
```
{% endtab %}
{% tab title="401 " %}
```
{
"error": "Question inaccessible Error id : 1583414902648/mOXsfkd7."
}
```
{% endtab %}
{% endtabs %}
### Request Return type
Returns [Question Data object](/v.5.0.2/api/questions#question-data-object)
# Surveys
### Survey data object
| Field | Type | Example | Description |
| -------------- | --------- | ------------------------------------------------------ | ------------------------------------------------------- |
| teamId | string | "5a3386af952bf6000177bdda" | Team id |
| languages | string\[] | \["en", "es"] | List of available languages for the survey |
| name | string | "Satisfaction survey" | Survey name |
| \_id | string | "5a3386af952bf6000177bdda" | Survey id |
| language | string | "en" | Language used to display titles, choices etc |
| teamName | string | "My team name" | Team name |
| createdBy | string | "Khal Drogo" | User name |
| archived | boolean | false | Whether the survey is archived |
| questions | array | | Questions embedded within the survey |
| > \_id | string | "5a3386af952bf6000177bdda" | Question id |
| > questionType | string | "NPS" | [See Question types](/v.5.0.2/api/notes#question-types) |
| > title | string | "How would you recommend us to a friend or colleague?" | Question title |
| > choices | array | | Question choices |
| >> fieldId | string | "1" | The id of the field |
| >> fieldName | string | "Beef" | The label of the choice |
| >> type? | string | "string" | Type of field (Contact question type) |
| >> subType? | string | "tel" | Subtype of the field (Contact question type) |
| >> imageUrl? | string | "" | Image url of the choice (Image question type) |
# GET Surveys
## Surveys
`GET` `https://api.feedbackly.com/v5.0.2/surveys`
This endpoint returns all available surveys with the questions embedded
#### Query Parameters
| Name | Type | Description |
| ----------------- | ------ | ------------------------------------------ |
| skip | number | Number of documents to skip from the start |
| preferredLanguage | string | Preferred language to show the titles in |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------------------------------------------------------------------------------------ |
| Authorization | string | Authentication token to access the API eg: 'Authorization': 'ey0iuefg.834xcunerun348efnsd' |
{% tabs %}
{% tab title="200 Cake successfully retrieved." %}
```
{
"data": [
{
"_id": "589c16e487ef9860199cab3c",
"name": "Example",
"createdBy": "Admin",
"teamId": "5dc56d54b7c935069aefa9e2",
"teamName": "My team name",
"languages": ["en"],
"archived": false,
"questions": [
{
"_id": "5a3b47d0e90828878851a1f5",
"title": "Contact form",
"subtitle": "Please type in your details",
"choicesString": [
"EMAIL",
"PHONE"
],
"questionType": "Contact",
"languages": [
"en"
],
"language": "en",
"choices": [
{
"fieldId": "5a3c353aecee8cb220b0270c",
"fieldName": "EMAIL",
"type": "string",
"subType": "email"
},
{
"fieldId": "5a3c353eecee8cb220b0270d",
"fieldName": "PHONE",
"type": "string",
"subType": "tel"
}
],
"surveyId": "5a3b47c946d70600010fe412"
}
]
}
],
"paging": {
"next": null,
"previous": null
}
}
```
{% endtab %}
{% tab title="404 Could not find a cake matching this query." %}
```
```
{% endtab %}
{% endtabs %}
### Request return type
| Field | Type | Example | Description |
| ------ | ----------------------------------------------------------------- | ------- | ------------------- |
| data | [Survey data object](/v.5.0.2/api/surveys#survey-data-object) \[] | | Survey data objects |
| paging | [Pagination](/v.5.0.2/api/notes/pagination) | | Pagination object |
# GET Surveys by id
## Survey by id
`GET` `https://api.feedbackly.com/v5.0.2/surveys/:id`
Gets question by id
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ---------------- |
| id | string | Id of the survey |
#### Query Parameters
| Name | Type | Description |
| ----------------- | ------ | ---------------------------------------- |
| preferredLanguage | string | Preferred language to show the titles in |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------------------------------------------------------------------------------------ |
| Authorization | string | Authentication token to access the API eg: 'Authorization': 'ey0iuefg.834xcunerun348efnsd' |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
### Request return type
Returns [Survey data object](/v.5.0.2/api/surveys#survey-data-object)
# Touchpoints
Touchpoints are the identifiable sources of all responses.
### Touchpoint data model
| Field | Type | Example | Description |
| ---------------- | ------ | -------------------------- | -------------------------------------------- |
| \_id | string | "507f191e810c19729de860ea" | Unique id |
| name | string | "Feedback terminal" | Name of the touchpoint |
| teamId | string | "507f191e810c19729de860eb" | Team id this touchpoint belongs to |
| activeSurveyId | string | "507f191e810c19729de860ec" | Id of the active survey on this touchpoint |
| activeSurveyName | string | "NPS Survey" | Name of the active survey on this touchpoint |
| lastResponse | number | 1598017724 | UNIX timestamp of the last response |
| lastResponseDate | string | "2020-08-21T13:49:44.951Z" | Last response in ISO String format |
# GET Touchpoints
## Get Touchpoints
`GET` `https://api.feedbackly.com/v5.0.2/touchpoints`
This endpoint allows you to access Touchpoint objects from Feedbackly.
#### Query Parameters
| Name | Type | Description |
| ------ | ------ | ------------------------------------------ |
| teamId | string | Filter touchpoints by teamId |
| skip | number | Number of documents to skip from the start |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| Authorization | string | Authentication token to access the API eg:
'Authorization': 'ey0iuefg.834xcunerun348efnsd'
|
{% tabs %}
{% tab title="200 Response successfully retrieved." %}
```
{
"data": [
{
"_id": "5dc57703b7c935069aef31c5",
"name": "Feedback terminal 1",
"teamId": "5dc57703b7c935069aef31c1",
"activeSurveyId": "5dc57703b7c935069aef31a2",
"activeSurveyName": "NPS Survey",
"lastResponse": 159801789,
"lastResponseDate": "2020-08-21T13:52:01.606Z"
},
{
"_id": "5dc57703b7c935069aef31c6",
"name": "Web widget home page",
"teamId": "5dc57703b7c935069aef31c2",
"activeSurveyId": "5dc57703b7c935069aef31a1",
"activeSurveyName": "CES Survey",
"lastResponse": 159801789,
"lastResponseDate": "2020-08-21T13:52:01.606Z"
}
],
"paging": {
"next": "https://api.feedbackly.com/v5.0.2/touchpoints?skip=200",
"previous": "https://api.feedbackly.com/v5.0.2/touchpoints?skip=0"
}
}
```
{% endtab %}
{% endtabs %}
### Response type description
| Field name | Type | Example | Description |
| ---------- | --------------------------------------------------------------------- | ------- | ------------------------------- |
| data | [Touchpoint data](/v.5.0.2/api/touchpoints#touchpoint-data-model) \[] | | The array of touchpoint objects |
| paging | [Pagination](/v.5.0.2/api/notes/pagination) | | Pagination object |
# GET Touchpoint by id
## Get Touchpoint by id
`GET` `https://api.feedbackly.com/v5.0.2/touchpoints/:id`
This endpoint allows you to access Touchpoint objects by id from Feedbackly.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------------- |
| id | string | Id of the touchpoint |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| Authorization | string | Authentication token to access the API eg:
'Authorization': 'ey0iuefg.834xcunerun348efnsd'
|
{% tabs %}
{% tab title="200 Response successfully retrieved." %}
```
{
"_id": "5dc57703b7c935069aef31c5",
"name": "Feedback terminal 1",
"teamId": "5dc57703b7c935069aef31c1",
"activeSurveyId": "5dc57703b7c935069aef31a2",
"activeSurveyName": "NPS Survey",
"lastResponse": 159801789,
"lastResponseDate": "2020-08-21T13:52:01.606Z",
}
```
{% endtab %}
{% endtabs %}
### Response type description
| Field name | Type | Example | Description |
| ---------- | --------------------------------------------------------------------- | ------- | ------------------------------- |
| data | [Touchpoint data](/v.5.0.2/api/touchpoints#touchpoint-data-model) \[] | | The array of touchpoint objects |
| paging | [Pagination](/v.5.0.2/api/notes/pagination) | | Pagination object |
# Notes
# Entity relationships
### Survey
Survey is the main container for several Questions. Each Question refers to a screen on a survey. In the REST API structure, survey returns an array of Questions.
### Question
Question refer to a screen inside a survey and is normally returned as a part of a Survey call. Each Question can also be retrieved invidually via the Questions API. Questions can be part of many surveys but this is a rare case (custom applications).
### Response chain
Response chain is a whole answer to one entire survey. The contents of the responses field is an array of one or more responses depending on which questions the respondent has answered. If the survey has been not answered fully the responses field will only contain the responses up to the point of exit by the customer. Also, skipping logic applied via the survey can result into varying sets of responses by the user.
### Response
A Response is an answer to an individual **field** of a Question. Regularly you only have 1 field inside the Question but for Slider and Contact question types the answers are separate Response objects. Each Response shares the `responseChainId` as a foreign key but those fields have a `fieldId` which links to the specific `choice.fieldId` inside a Question.
### Touchpoints
Touchpoints are the source of the incoming responses. This can be an individual Feedbackly terminal, a web widget, an email list etc. Responses have a unique `touchpointId` and a `touchpointName` to further clarify the source of responses. Each Response chain can only have one touchpoint because it represents one session (one respondent).
# Pagination
For endpoints that returns multiple objects, pagination is done by providing the URL's to get the next objects (if more are available)
| Field | Example |
| -------- | ------------------------------------------------------ |
| next | |
| previous | |
# Question types
This table clarifies the different outputs per question type
| Question type | Description | Field | Example | |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Button | Smileys / Satisfaction
The values are in the scale of 0-1.
5 buttons: 0, 0.25, 0.5, 0.75, 1
4 buttons: 0, 0.33, 0.66, 1
| valueNum: number
answer: number
| valueNum: 0.5
answer: 0.5
| |
| NPS | NPS question
Numbers 0-10
| valueNum: number
answer: number
| valueNum: 4
answer: 4
| |
| Word | Category / Selection / Multiselect
Answer will either be a string value if the
question is single select or an array of strings
if the question is a multi-select.
valueArray will contain the unique id's of the
choice(s) selected while answer contains the
string representations of the choice in the language chosen
| valueArray: string\[]
answer: string | string\[]
| Multiselect:
valueArray: \['sdfs3, 'asdas1]
answer: \['Apples', 'Oranges']
Single select:
valueArray: \['533rf']
answer: 'Pears'
|
| Image | Category / Selection by image
Same as above
| Same as above | Same as above, outputs image labels | |
| Slider | Slider question. These questions contain multiple responses depending on the field responded to. In order to connect these answers together, you look at the responseChainId and the questionId
Each field contains a fieldId and a fieldName to distinguish the responses apart.
The scale is 0-10.
| valueNum: number
answer: number
| valueNum: 4
answer: 4
| |
| Contact | Contact form question. Like Slider question, this question might have multiple responses per question. | valueString: string
answer: string
| valueString: ""
answer:
""
| |
| Text | Open-ended field. | valueString: string
answer: string
| valueString: "I was happy"
answer: "I was happy"
| |
# Getting started
## Installing the website widget
### Verifying installation
Go to your website and open up the developer console in your browser. In Chrome, this can be done via the command `⌘ + option + J`
Find the console from the bottom of the developer tools. Type in `FBLY` and press enter. If your plugin is installed properly, the command should return `true`. Your plugin is all set up!
If the script is not installed, you'll get an error like so:
If this is the case, please verify that the plugin is installed properly on your website.
# Attaching custom metadata to responses
## Overview
Custom metadata is any additional information you wish to include in your response. This metadata will be available in the Response list in the analytics section in Feedbackly. You can also filter and group responses by metadata.
Metadata will be included to the subsequent survey responses made by the visitor on the site. Metadata will always be included in responses until it is cleared or the user resets their browser cookies.
Note: Metadata can be added at any point of time **before** a survey is launched.
### Using the Javascript API to include metadata to the response
When the Feedbackly widget is installed on the site, run
```
FBLY.action("addMeta", KEY, VALUE);
```
Example:
`FBLY.action("addMeta", "customerId", "12345");`
This command adds a customer id to the subsequent responses of the user.
### Removing a single metadata value from the visitor
This action will a single metadata key and value from the visitor. It does not affect previous responses given by the user, however.
```
FBLY.action("removeMeta", KEY)
```
Example:
`FBLY.action("removeMeta", "customerId")`
This action removes the customerId set in the previous example.
### Clearing all metadata from a visitor
This action will clear all the metadata from the visitor. It does not affect previous responses given by the user, however. This action needs to be run before a survey is launched.
Using Javascript, run
```
FBLY.action("clearMeta")
```
# Triggering surveys via custom properties
### Overview
Custom triggering properties are used to have a more fine-grained control over the triggering properties of a Feedbackly website widget.
For instance, you might want to trigger a survey based on whether a customer is logged in to the members' are in your website. This can be easily accomplished provided that there is Javascript access to the information required to set the triggering behavior.
### Set up custom triggering parameters in the Feedbackly dashboard
In the website triggering options, open up *Advanced targeting* and add the property under *Custom Properties* like so
### Adding a custom triggering property to the Feedback widget via the Javascript API
When the Feedbackly widget is installed, run
```
FBLY.action("addCustomProperty", KEY, VALUE)
```
**Example**
Let's assume the information of the logged in status is stored in a Javascript variable accessible in the namespace the widget command is run. For this example, we'll assume it's stored in `user.loggedIn` variable.
Running `FBLY.action("addCustomProperty", "loggedIn", "true")` will tell the widget that the user is logged in. If the widget triggering settings has that property set, the survey will then trigger (if no other restrictions are set)
### Removing a single custom triggering property
When you want to prevent further surveys from displaying because of a custom property
When the Feedbackly widget is installed, run
```
FBLY.action("removeCustomProperty", KEY)
```
**Example**
Following the previous example, if we want to remove a custom triggering property (let's say the user logs out) we would run this command:
`FBLY.action("removeCustomProperty", "loggedIn")`
### Clearing all custom properties
This command clears all custom triggering properties of the visitor
```
FBLY.action("clearCustomProperties")
```
# Debugging website widgets
Due to the amount of variables it's not always straightforward to figure out why exactly a survey triggers/doesn't open for a visitor.
To find out more about the underlying reasons, Feedbackly provides the means to debug this.
If you need to check the installation status of a widget, please see [Verifying installation.](/v.5.0.2/website-widgets/getting-started#verifying-installation)
### List all triggering options available to the visitor
When on your website and with Feedbackly widget installed, open up the dev tools for the browser. In Chrome, this can be done via the command `⌘ + option + J`
Run the following command:
```
FBLY.getConfiguration();
```
The console should print out an array of configuration objects similar to this:
This is in essence the JSON-representation of your website triggering parameters available on the Feedbackly UI's widget triggering parameters. All the objects in this array are the potential surveys to be shown to the user when conditions are met.
### Listing client data
To find out what data the widget has recorded of the visitor, run
```
FBLY.getConfiguration();
```
This data can be useful in determining whether the visitor has met the conditions for a survey to be triggered.
A few remarks on the properties:
* `session.declinedActivations` lists whether the user has declined a survey, its id and timestamp
* `session.sampledActivations` shows whether the visitor fits to the sample of the survey
* `visitedUrls` shows all visited urls of the visitor
* `scroll` shows the current page scroll of the visitor