Doorbell.io Feedback Capture API documentation
Basics
This is the API for capturing user feedback and saving it in Doorbell (if you're planning on writing your own widget).
The base URL for the API is: https://doorbell.io/api
All requests should be POST requests.
Please provide a useful User-Agent header with each request!
Authentication
Doorbell has an application ID and a secret key that need to be used when making API calls. The ID constructs part of the URL in each call (/applications/{id}/{action}), and the key should always be passed as a query string parameter, using the name key. (e.g. https://doorbell.io/api/applications/1/open?key=key-goes-here)
To obtain an application ID/key, you need to register here on Doorbell, create an application, go to the setup page, and copy the ID/Key from the API tab.
Endpoints
POST /applications/{id}/open
Open
Request sent when the form is displayed to the user.
Query string parameters
| Name | Description |
|---|---|
key |
The application key |
Responses
| HTTP Code | Content Type | Response Body |
|---|---|---|
201 |
plain/text |
OK |
403 |
plain/text |
Not authorized |
404 |
plain/text |
Invalid application |
POST /applications/{id}/submit
Submit
Request sent when the form is submitted.
Query string parameters
| Name | Description |
|---|---|
key |
The application key |
Request Body
Content-Type: application/json
| Name | Required | Description | Example |
|---|---|---|---|
email |
The email address of the user sending feedback | hello@example.com | |
message |
The feedback message the user has entered | Hello! Loving this app! | |
name |
The name of the user who is sending feedback | John Doe | |
ip |
The IP address of the end user, so your server's IP address isn't the one saved | 3.148.108.192 | |
sentiment |
The sentiment of the message, if you don't want this analyzed automatically. The possible values are positive, neutral, or negative |
positive | |
url |
The URL of the page where feedback is submitted from (if applicable) | https://example.com/some/page | |
tags |
JSON encoded array of strings, or a comma separated string of tags you want to add to the feedback | ["bug-reports","second-tag"] | |
properties |
JSON encoded string of properties (of any data type), any extra metadata you want to attach to the message | {"user_id":29333,"username":"daniele"} | |
attachments |
Array of attachment IDs (get these from uploading to the upload endpoint |
[566,290,882] | |
nps |
The NPS rating the user submitted alongside the message | 10 | |
language |
The language the site/app is using. The response messages will be in the corresponding language, if translated |
|
Responses
| HTTP Code | Content Type | Response Body |
|---|---|---|
201 |
plain/text |
Feedback sent! |
400 |
plain/text |
Your email address is required |
400 |
plain/text |
Invalid email address |
400 |
plain/text |
Your message is required |
400 |
plain/text |
Your message is too short |
403 |
plain/text |
Not authorized |
404 |
plain/text |
Application not found |
POST /applications/{id}/upload
Upload
Request sent when uploading an attachment (for the subsequent submit request).
The endpoint (on success) will return a JSON array of IDs. These IDs need to be supplied to the submit request afterwards.
Query string parameters
| Name | Description |
|---|---|
key |
The application key |
POST Parameters
- Multipart form request, including any number of files
Responses
| HTTP Code | Content Type | Response Body |
|---|---|---|
201 |
application/json |
A JSON array containing the attachment IDs of the files uploaded |
400 |
plain/text |
Uploads not enabled |
400 |
plain/text |
No files found (this could mean an error in how the files are sent) |
403 |
plain/text |
Not authorized |
404 |
plain/text |
Invalid application |
POST /applications/{id}/event
Track an event
Request sent to track an event, which can in turn trigger a prompt to show the form (if the defined conditions are met).
The endpoint (on success) will return a JSON object with the event_id and the action to be taken (for example, show the form). These event ID can be supplied to the submit request afterwards.
Query string parameters
| Name | Description |
|---|---|
key |
The application key |
Request Body
Content-Type: application/json
| Name | Required | Description | Example |
|---|---|---|---|
external_user_id |
A unique identifier for this user. Could be an email address, or any other unique identifier from your system. | hello@example.com or 47344559-a613-4be7-b7ae-0d499e0c8cf8 |
|
name |
The name of the event we are tracking | logged_in or added_item_to_basket |
|
attributes |
JSON object, any extra metadata you want to attach to the message (key-value pairs) | {"country_code":"GB","item_value":"17.31"} |
Responses
| HTTP Code | Content Type | Response Body |
|---|---|---|
201 |
application/json |
A JSON object with the event_id and the action |
400 |
plain/text |
Missing event name |
400 |
plain/text |
Missing external user ID |
403 |
plain/text |
Not authorized |
404 |
plain/text |
Invalid application |