Doorbell.io logoDoorbell.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.144.96.92
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":56988,"username":"shakira"}
attachments Array of attachment IDs (get these from uploading to the upload endpoint [845,440,876]
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
  • en
  • es
  • pt

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
You can translate all the responses above

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 523dacbd-295d-42a4-81f2-ca6d4906e0af
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":"23.8"}

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