Implementation guide
How to Add a Feedback Widget to Your Website
Go from an inbox and a script tag to a verified response. Configure the prompt, placement, and context for your own website.
This guide takes a Pollenate website feedback widget from setup to a verified response in your inbox. You need a page that allows custom JavaScript and a Pollenate account with permission to create an inbox and a collection key.
1. Create the inbox and collect-only key
Create an inbox in the brand that owns the site. Copy its inbox key, which is different from its display name. In Settings → API Keys, create an organization key with the collect scope, restricted to the relevant brand when appropriate.
The public /collect endpoint uses organization keys. Personal API keys and OAuth sign-in are useful for other workflows, such as MCP assistants, but are not accepted by this endpoint. Never put an administrative key in browser code.
2. Add the script
Place this before the closing </body> tag and replace the two placeholders:
<script
src="https://pollenate.dev/widget.js"
data-inbox-key="YOUR_INBOX_KEY"
data-api-key="YOUR_COLLECT_KEY"
data-type="emoji"
data-theme="auto"
data-strip-query-params="true"
defer
></script>
The widget defaults to a floating button in the bottom-right corner. data-theme="auto" follows the visitor’s system preference; without it, the default is light. defer delays execution until the HTML has been parsed. The widget still has a network and rendering cost, so verify performance with your own site.
Website builders may restrict custom scripts by plan or location. Publish and test the actual page rather than relying only on an editor preview. In a React or Next.js application, use the framework guide instead of adding a new script on every render.
3. Match the prompt to the task
| Attribute value | Response | Example question |
|---|---|---|
thumbs |
0 or 1 | Was this helpful? |
stars |
1–5 stars | How was your experience? |
emoji |
1–5 reaction | How did setup feel? |
nps |
0–10 | How likely are you to recommend us? |
csat |
1–5 | How satisfied are you? |
text |
Written feedback | What should we improve? |
Change data-type and set a specific data-prompt. For a short interaction, prefer a clear question and an optional comment. Let your application decide when and where to render the widget; the script does not provide a built-in behavioral targeting engine for timers and scroll rules.
4. Put it where it belongs
To show an inline prompt beneath an article, add a container and point the script at it:
<div id="article-feedback"></div>
<script
src="https://pollenate.dev/widget.js"
data-inbox-key="YOUR_INBOX_KEY"
data-api-key="YOUR_COLLECT_KEY"
data-type="thumbs"
data-prompt="Was this article helpful?"
data-container="#article-feedback"
data-theme="auto"
data-primary-color="#b45309"
data-context='{"surface":"documentation","version":"v2"}'
data-strip-query-params="true"
defer
></script>
Use this instead of the floating example, not in addition to it. data-container implies inline mode. Supported attributes also control colors, width, font, corner radius, button copy, and the thank-you message. Find the full list in the widget documentation.
The data-context attribute must contain valid JSON. It adds your metadata to the event; data-meta-plan and similar attributes are not supported. The widget captures the current page URL when a response is submitted. Review URL and metadata collection for your application’s needs.
5. Confirm the response reaches the right inbox
Submit a recognizable test comment and inspect your browser’s Network panel. The /collect request should return HTTP 201 with an id and success: true. Then open Pollenate and verify that the score, comment, and page context arrived in the intended inbox.
| Result | Check next |
|---|---|
| Widget does not appear | The script loaded, the required attributes are present, and the container exists |
| 400 | The request body and field types |
| 401 | The organization key and whether it expired or was revoked |
| 403 | The collect scope and the inbox’s organization/brand |
| 404 | The inbox key |
| 429 | The response’s usage or request-limit information; wait before retrying |
| Request blocked | Browser console, content security policy, extensions, and network connectivity |
For a content security policy, permit the script origin and API connection in the appropriate directives. The widget also injects styles, so a strict style policy needs deliberate configuration. Do not weaken an existing policy indiscriminately; test the widget against it.
6. Decide what happens after feedback arrives
The widget emits pollenate:submit after a successful submission. You can use the event for an application confirmation or your own analytics:
window.addEventListener('pollenate:submit', (event) => {
console.log('Accepted feedback ID:', event.detail.id);
});
Avoid sending full comments to unrelated analytics systems. In Pollenate, review responses and use email/webhook automations for follow-up. If your team needs a longer survey, create a Feedback Page.
Create your first widget or see the developer API for a custom interface.