Documentation

💡How Pollenate Works

Pollenate helps you hear from the people who use your product, visit your website, or walk through your door. It collects their feedback — ratings, comments, survey responses — and organizes it all in one dashboard so you can spot patterns and take action.

🚀Quick Start

Get up and running with Pollenate in under 5 minutes. Collect your first piece of feedback today.

<script 
  src="https://pollenate.dev/widget.js"
  data-inbox-key="YOUR_INBOX_KEY"
  data-api-key="YOUR_API_KEY"
  data-type="emoji"
  async
></script>

That's it! The widget will automatically appear on your page. You'll need both an inbox key (from the Inboxes page) and an API key with the "collect" scope (from Settings → API Keys).

🔐Authentication

Pollenate uses two authentication methods depending on your use case:

curl -X POST https://api.pollenate.dev/collect \
  -H "X-Pollenate-Key: pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"type": "emoji", "score": 5, "comment": "Great!"}'

curl https://api.pollenate.dev/organizations \
  -H "Authorization: Bearer eyJhbGc..."

📦Embed Widget

The Pollenate widget can be embedded in any website with a single script tag.

Script Attributes

🎨Widget Types

Pollenate offers six different ways to ask for feedback. Choose the one that fits what you're trying to learn. Not sure which to pick? Emoji and Stars work great for most situations.

🎭Customization

Customize the widget appearance using CSS variables or create custom themes in the dashboard.

:root {
  --pollenate-primary: #f59e0b;
  --pollenate-primary-hover: #d97706;
  --pollenate-bg: #ffffff;
  --pollenate-text: #1e293b;
  --pollenate-border: #e2e8f0;
  --pollenate-radius: 12px;
}

⚛️React Package

For React apps, install @pollenate/react for a fully typed, native React component — no script tags or DOM manipulation needed.

Installation

npm install @pollenate/react
# or
pnpm add @pollenate/react
# or
yarn add @pollenate/react

Quick Start

import { PollenateWidget } from '@pollenate/react';

export function App() {
  return (
    <PollenateWidget
      inboxKey="YOUR_INBOX_KEY"
      apiKey="YOUR_API_KEY"
      type="stars"
      theme="auto"
      onSubmit={(event) => {
        console.log('Feedback submitted:', event.detail);
      }}
    />
  );
}

Inline Widget

Add inline to render the widget directly in your page flow instead of as a floating button:

<PollenateWidget
  inboxKey="my-inbox"
  apiKey="pk_live_xxx"
  type="thumbs"
  inline
  prompt="Was this page helpful?"
/>

Custom Themed

Override colors, border radius, fonts, and dark-mode colors:

<PollenateWidget
  inboxKey="my-inbox"
  apiKey="pk_live_xxx"
  type="nps"
  theme="auto"
  primaryColor="#6366f1"
  borderRadius={12}
  buttonText="Submit Score"
  darkPrimaryColor="#818cf8"
  darkBgColor="#1e1b4b"
  hideBranding
/>

Props Reference

🛠️Custom Widgets

Want complete control over your feedback UI? Build your own custom widget using our REST API. This allows you to match your brand perfectly and integrate feedback into any user flow. If you're using React, consider the @pollenate/react package first — it handles all the API calls and UI for you.

Basic Example

Here's a complete example of a custom feedback form using vanilla HTML/JavaScript:

<form id="custom-feedback">
  <p>How would you rate your experience?</p>
  <div class="rating-buttons">
    <button type="button" data-score="1">😞</button>
    <button type="button" data-score="2">😐</button>
    <button type="button" data-score="3">🙂</button>
    <button type="button" data-score="4">😄</button>
    <button type="button" data-score="5">🤩</button>
  </div>
  <textarea name="comment" placeholder="Any additional feedback?"></textarea>
  <button type="submit">Submit</button>
</form>

<script>
let selectedScore = null;

document.querySelectorAll('[data-score]').forEach(btn => {
  btn.onclick = () => selectedScore = parseInt(btn.dataset.score);
});

document.getElementById('custom-feedback').onsubmit = async (e) => {
  e.preventDefault();
  
  const response = await fetch('https://api.pollenate.dev/collect', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Pollenate-Key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      inboxKey: 'YOUR_INBOX_KEY',
      type: 'emoji',
      score: selectedScore,
      comment: e.target.comment.value,
      context: {
        page: window.location.pathname,
        userAgent: navigator.userAgent
      }
    })
  });
  
  if (response.ok) {
    alert('Thank you for your feedback!');
  }
};
</script>

React Example (DIY)

This shows how to build a completely custom feedback UI from scratch using the API directly. For a drop-in solution, see the React Package section above.

import { useState } from 'react';

export function CustomFeedback() {
  const [score, setScore] = useState(null);
  const [comment, setComment] = useState('');
  const [submitted, setSubmitted] = useState(false);

  const handleSubmit = async () => {
    const response = await fetch('https://api.pollenate.dev/collect', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Pollenate-Key': process.env.POLLENATE_API_KEY
      },
      body: JSON.stringify({
        inboxKey: 'YOUR_INBOX_KEY',
        type: 'emoji',
        score,
        comment,
        context: { page: window.location.pathname }
      })
    });
    
    if (response.ok) setSubmitted(true);
  };

  if (submitted) return <p>Thanks for your feedback! 🎉</p>;

  return (
    <div className="feedback-widget">
      <p>How was your experience?</p>
      <div className="emojis">
        {['😞', '😐', '🙂', '😄', '🤩'].map((emoji, i) => (
          <button
            key={i}
            onClick={() => setScore(i + 1)}
            className={score === i + 1 ? 'selected' : ''}
          >
            {emoji}
          </button>
        ))}
      </div>
      <textarea
        value={comment}
        onChange={(e) => setComment(e.target.value)}
        placeholder="Tell us more..."
      />
      <button onClick={handleSubmit} disabled={!score}>
        Submit Feedback
      </button>
    </div>
  );
}

API Request Format

Score Ranges by Type

Using Context for Insights

The context field lets you attach metadata to each feedback submission. This enables powerful filtering and analysis in your dashboard.

// Example context object
{
  "context": {
    "page": "/checkout",
    "userId": "user_abc123",
    "plan": "pro",
    "feature": "dark-mode",
    "experiment": "new-pricing-v2",
    "sessionId": "sess_xyz789"
  }
}

📋Feedback Pages

Feedback Pages are standalone, branded feedback forms that you create through the Pollenate dashboard. Unlike widgets (which embed into existing pages), Feedback Pages are hosted at their own URL and can collect multi-question surveys from users.

Key Features

🔨Form Builder

The form builder lets you create multi-question feedback forms using a visual editor. Each question has a type, prompt, optional description, and can be marked as required.

Supported Question Types

Page Settings

📋Import from Google Forms

Already have a Google Form? You can migrate it to a Pollenate feedback page in a couple of clicks — no Apps Script, no OAuth, and no AI calls. Pollenate fetches the public form, parses its questions, and creates a matching feedback page for you to review and edit.

Steps

1. In Google Forms, make sure the form is shared with Anyone with the link (Settings → Responses → toggle off "Restrict to users").
2. Copy the form's URL. Both docs.google.com/forms/... and forms.gle/... short links work. Editor URLs (/edit) are normalized to /viewform automatically.
3. In Pollenate, open Feedback Pages → click + New Page → choose the Google Forms tab.
4. Paste the URL and click Import. You'll see a preview of the parsed title, description, and questions.
5. Click Create Page to save. The new page opens in the editor where you can tweak anything before publishing.

Question Type Mapping

What Doesn't Carry Over

The public Google Forms payload doesn't expose a handful of editor-only settings, so these aren't imported:

• Confirmation / "form has been submitted" message
• "Collect email addresses" setting
• "Limit to one response per user" setting
• Grid, time, and file-upload question types
• Images and videos (caption text is imported)

Troubleshooting

• "Form is not publicly accessible" — open the Google Form's sharing settings and make sure it's set to Anyone with the link. Forms restricted to a Google Workspace can't be imported.
• "Could not find form data" — Google occasionally changes the embedded payload format. Try re-saving the form in Google Forms, or copy the questions manually using the form builder.
• Some questions are missing — check the import warning for the list of unsupported types (grid, time, file upload). Re-add them manually after importing.

🔗Sharing & Embedding

Once your Feedback Page is published, you have multiple ways to share it with respondents.

https://pollenate.dev/f/your-org/your-page-slug

GET https://api.pollenate.dev/qr?data=YOUR_PAGE_URL&size=256&format=png&margin=4

Parameters:
  data    - URL to encode (required)
  size    - Image size in pixels: 128, 256, 512, 1024 (default: 256)
  format  - Output format: png or svg (default: png)
  margin  - Quiet zone margin in modules (default: 4)

<table cellpadding="0" cellspacing="0" border="0">
  <tr>
    <td style="padding: 10px 0;">
      <a href="https://pollenate.dev/f/your-org/your-page"
         style="display: inline-block; padding: 8px 16px;
                background-color: #f59e0b; color: #ffffff;
                text-decoration: none; border-radius: 6px;
                font-family: Arial, sans-serif; font-size: 14px;">
        Share Your Feedback
      </a>
    </td>
  </tr>
</table>

<iframe
  src="https://pollenate.dev/f/your-org/your-page?embed=true"
  width="100%"
  height="600"
  frameborder="0"
  style="border: none; border-radius: 12px;"
  title="Feedback Form"
></iframe>

⚙️Pages API

Manage Feedback Pages programmatically via the REST API. All endpoints require JWT Bearer token authentication.

Submit Responses (Public)

{
  "answers": {
    "question-id-1": { "score": 5 },
    "question-id-2": { "textValue": "Great experience!" },
    "question-id-3": { "multiValues": ["Search", "Referral"] }
  },
  "respondentName": "Jane Doe",
  "respondentEmail": "jane@example.com",
  "turnstileToken": "CAPTCHA_TOKEN"
}

⚡API Overview

The Pollenate API is a RESTful API that uses JSON for request and response bodies.

For the complete API specification, see our OpenAPI 3.1 spec.

📥Feedback Collection

{
  "type": "emoji",        // emoji, stars, thumbs, nps, csat, text
  "score": 5,             // 0-10 for nps, 1-5 for others
  "comment": "Loving it!",// Optional text feedback
  "context": {            // Optional metadata
    "page": "/checkout",
    "userId": "user_123"
  }
}

{
  "id": "fb_abc123",
  "createdAt": "2026-02-04T12:00:00Z"
}

📬Inboxes

Inboxes are containers for feedback. Each inbox has a unique key used to submit feedback.

🔍Semantic Search

Search feedback using natural language. Powered by AI embeddings for semantic understanding.

{
  "query": "users frustrated with checkout",
  "limit": 20,
  "filters": {
    "inboxId": "inbox_123",
    "minScore": 1,
    "maxScore": 3
  }
}

🤖AI Agent Integration

AI agents can submit feedback during conversations with users — capturing satisfaction, sentiment, and product feedback in real-time without interrupting the flow.

# Install the skill locally for your AI agent
mkdir -p ~/.agent/skills/pollenate
curl -s https://pollenate.dev/skill.md > ~/.agent/skills/pollenate/SKILL.md
curl -s https://pollenate.dev/skill.json > ~/.agent/skills/pollenate/skill.json

{
  "mcpServers": {
    "pollenate": {
      "type": "streamableHttp",
      "url": "https://api.pollenate.dev/mcp",
      "headers": {
        "Authorization": "Bearer pk_live_YOUR_API_KEY"
      }
    }
  }
}

{
  "servers": {
    "pollenate": {
      "type": "streamableHttp",
      "url": "https://api.pollenate.dev/mcp",
      "headers": {
        "Authorization": "Bearer pk_live_YOUR_API_KEY"
      }
    }
  }
}

curl -X POST https://api.pollenate.dev/collect \
  -H "Content-Type: application/json" \
  -H "X-Pollenate-Key: YOUR_API_KEY" \
  -d '{
    "inboxKey": "support-chat",
    "type": "thumbs",
    "score": 1,
    "comment": "User confirmed their issue was resolved",
    "context": {
      "source": "ai-agent",
      "agentName": "SupportBot",
      "topic": "password-reset"
    }
  }'

curl -X POST https://api.pollenate.dev/collect \
  -H "Content-Type: application/json" \
  -H "X-Pollenate-Key: YOUR_API_KEY" \
  -d '{
    "inboxKey": "sentiment-tracker",
    "type": "emoji",
    "score": 4,
    "context": {
      "source": "ai-agent",
      "detectedSentiment": "positive",
      "conversationTurns": 8,
      "agentModel": "claude-sonnet-4"
    }
  }'

curl -X POST https://api.pollenate.dev/collect \
  -H "Content-Type: application/json" \
  -H "X-Pollenate-Key: YOUR_API_KEY" \
  -d '{
    "inboxKey": "product-feedback",
    "type": "text",
    "comment": "User requested dark mode support — 3rd request this week",
    "context": {
      "source": "ai-agent",
      "category": "feature-request",
      "priority": "high"
    }
  }'

⚡Automations & Integrations

An automation rule is a simple recipe: when an event happens (a trigger), optionally matching some conditions (filters), do something (an action). You manage rules from Dashboard → Automations, or directly via the API. Every rule execution is logged with its status, HTTP status code, and duration so you can debug deliveries.

Rule scope

Rules can be scoped to a single inbox or to your whole organization:

🎯Events & Filters

Each rule listens for one or more events and can narrow down which of those events actually trigger the action using filters. An empty filter set matches everything.

Events

Filters for feedback.created

Filters for page_response.created

Create a rule via the API

Send a low-score webhook for an inbox, but only when there's a written comment:

curl -X POST https://api.pollenate.dev/organizations/ORG_ID/automations \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Low NPS to webhook",
    "scope": "inbox",
    "inboxId": "INBOX_ID",
    "type": "webhook",
    "target": "https://example.com/hooks/pollenate",
    "events": ["feedback.created"],
    "filters": {
      "type": "nps",
      "npsCategory": "detractor",
      "hasComment": true
    }
  }'

🔗Webhooks

When a webhook rule fires, Pollenate sends an HTTP POST request to your target URL with a JSON body and a set of identifying headers. Deliveries time out after 10 seconds; a 2xx response is treated as success and anything ≥ 400 is logged as a failure.

Request headers

Payload shape

Every payload is wrapped in an envelope with the event, a timestamp, and the event-specific data. Here's a feedback.created payload:

{
  "event": "feedback.created",
  "timestamp": "2026-06-05T14:23:11.482Z",
  "data": {
    "feedbackId": "fb_a1b2c3",
    "inboxId": "inbox_123",
    "inboxName": "Website",
    "inboxKey": "pk_live_abc",
    "brandId": "brand_1",
    "brandName": "Acme",
    "orgId": "org_42",
    "orgName": "Acme Inc.",
    "type": "nps",
    "score": 2,
    "comment": "Checkout kept failing on mobile.",
    "pageUrl": "https://acme.com/checkout",
    "sessionId": "sess_789",
    "context": "checkout-flow",
    "source": "widget",
    "externalUserId": "user_55",
    "createdAt": "2026-06-05T14:23:11.000Z"
  }
}

And a page_response.created payload:

{
  "event": "page_response.created",
  "timestamp": "2026-06-05T14:25:02.110Z",
  "data": {
    "responseId": "resp_abc",
    "pageId": "page_99",
    "pageTitle": "Onboarding Survey",
    "pageSlug": "onboarding-survey",
    "orgId": "org_42",
    "orgName": "Acme Inc.",
    "brandName": "Acme",
    "respondentName": "Jordan Lee",
    "respondentEmail": "jordan@example.com",
    "answers": [
      {
        "questionId": "q1",
        "questionPrompt": "How easy was setup?",
        "questionType": "stars",
        "score": 4,
        "textValue": null,
        "multiValues": null
      }
    ],
    "createdAt": "2026-06-05T14:25:02.000Z"
  }
}

Verifying the signature

When you set a signing secret on the rule, Pollenate signs the raw request body with HMAC-SHA256 and sends the hex digest in the X-Pollenate-Signature header as sha256=<digest>. Recompute it on your side and compare to confirm the request genuinely came from Pollenate and wasn't tampered with.

import crypto from "node:crypto";

const SECRET = process.env.POLLENATE_WEBHOOK_SECRET;

// Use the RAW body, not the parsed JSON object.
app.post("/hooks/pollenate", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.header("X-Pollenate-Signature") || "";
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");

  const ok =
    signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

  if (!ok) return res.status(401).send("Invalid signature");

  const payload = JSON.parse(req.body.toString("utf8"));
  console.log("Verified Pollenate event:", payload.event);
  res.sendStatus(200);
});

🔐Secrets & Custom Headers

Webhook automations support three extra knobs that turn a basic webhook into a full HTTP request to any API:

• ✦HTTP method — choose POST, PUT, PATCH, DELETE, or GET.
• ✦Custom headers — add any request headers, e.g. an Authorization token or a specific Accept/Content-Type.
• ✦Body template — shape the request body exactly how the target API expects, using placeholders for event data.

The secrets store

Create named secrets under Dashboard → Automations → Manage secrets (or via the API). Each secret is encrypted at rest with AES-256-GCM and its value is never returned by the API again — you'll only ever see a masked hint like ••••cdef. Reference a secret anywhere in your headers or body template with {{secrets.NAME}}.

curl -X POST https://api.pollenate.dev/organizations/ORG_ID/secrets \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GITHUB_TOKEN",
    "value": "github_pat_11AAA...",
    "description": "Fine-grained PAT, Issues: read & write"
  }'

Templating

Header values and the body template support {{ ... }} placeholders. This is plain text substitution — there is no code execution — resolved against the event at delivery time:

Unknown placeholders resolve to an empty string. See the payload reference for every available data.* field.

🐙Recipe: Create a GitHub Issue

A common ask: "when a customer leaves negative feedback, open a GitHub issue so the team can triage it." With secrets and custom headers you can do this with a webhook that calls GitHub directly — no relay or extra service needed.

Option A — Direct webhook (recommended)

1. In Manage secrets, add a secret named GITHUB_TOKEN containing a fine-grained PAT with Issues: Read & write on the target repo.
2. Create a webhook automation for feedback.created with a filter such as scoreBelow: 3.
3. Set the URL, method, headers, and body template as shown below.

Body template:

{
  "title": "Feedback: {{data.type}} ({{data.score}}) on {{data.inboxName}}",
  "body": "**Comment:** {{data.comment}}\n\n**Score:** {{data.score}}\n**Source:** {{data.source}}\n**Page:** {{data.pageUrl}}\n**Feedback ID:** {{data.feedbackId}}",
  "labels": ["feedback", "needs-triage"]
}

Option B — No code (Zapier)

Prefer not to manage tokens at all? Use the Zapier app: a New Feedback trigger plus GitHub's Create Issue action, with a filter for negative feedback.

Option C — Webhook + relay

If you'd rather keep credentials entirely in your own infrastructure, send the webhook to a small relay (here, a Cloudflare Worker) that verifies the signature and calls the GitHub REST API.

export default {
  async fetch(request, env) {
    if (request.method !== "POST") return new Response("Method not allowed", { status: 405 });

    // 1. Read the RAW body so the signature still matches.
    const raw = await request.text();

    // 2. Verify the Pollenate signature (optional but recommended).
    const signature = request.headers.get("X-Pollenate-Signature") || "";
    const key = await crypto.subtle.importKey(
      "raw",
      new TextEncoder().encode(env.POLLENATE_WEBHOOK_SECRET),
      { name: "HMAC", hash: "SHA-256" },
      false,
      ["sign"],
    );
    const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(raw));
    const expected =
      "sha256=" +
      [...new Uint8Array(mac)].map((b) => b.toString(16).padStart(2, "0")).join("");
    if (signature !== expected) return new Response("Invalid signature", { status: 401 });

    // 3. Only act on negative feedback.
    const { event, data } = JSON.parse(raw);
    if (event !== "feedback.created" || (data.score ?? 99) > 3) {
      return new Response("Ignored", { status: 200 });
    }

    // 4. Create the GitHub issue.
    const res = await fetch("https://api.github.com/repos/OWNER/REPO/issues", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${env.GITHUB_TOKEN}`,
        Accept: "application/vnd.github+json",
        "User-Agent": "pollenate-relay",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        title: `Feedback: ${data.type} (${data.score}) on ${data.inboxName}`,
        body: [
          `**Comment:** ${data.comment || "(none)"}`,
          `**Score:** ${data.score}`,
          `**Source:** ${data.source}`,
          `**Page:** ${data.pageUrl || "n/a"}`,
          `**Feedback ID:** ${data.feedbackId}`,
        ].join("\n"),
        labels: ["feedback", "needs-triage"],
      }),
    });

    return new Response(res.ok ? "Issue created" : "GitHub error", {
      status: res.ok ? 200 : 502,
    });
  },
};

⚙️Zapier

Connect your account by creating an API key with the read + write scopes at pollenate.dev/api-keys (the link pre-selects the right scopes), then paste it into Zapier when prompted. Triggers use REST Hooks, so feedback flows through in real time rather than on a polling delay.

Example Zaps

• Feedback → Slack: post a message when NPS detractors leave a comment.
• Feedback → GitHub/Jira: auto-create an issue for negative feedback.
• Feedback → Google Sheets: log every entry to a spreadsheet for analysis.
• Typeform → Pollenate: pipe survey responses in as feedback.

🧩More Integrations

Because automations support generic webhooks, you can connect Pollenate to nearly anything:

• ✦Make, n8n, Pipedream: point a webhook rule at their "catch hook" URL and build flows visually — same payload and signature as described above.
• ✦Slack: use the Zapier "Slack → Send Channel Message" action, or relay through your own endpoint that posts to a Slack Incoming Webhook (Slack expects its own { text } body, so reshape the payload first).
• ✦Your own backend: receive webhooks directly and write to your database, queue, or analytics pipeline.
• ✦Email: the built-in email action delivers a formatted notification with no extra tooling required.

🛡️Content Security Policy (CSP)

If your website uses a Content Security Policy, you'll need to allow the Pollenate widget script and API endpoints. Without the correct CSP directives, the widget will load but fail to submit feedback or track impressions.

Refused to connect to 'https://api.pollenate.dev/collect' because it violates the document's Content Security Policy.

[Pollenate] Error: TypeError: Failed to fetch. Refused to connect because it violates the document's Content Security Policy.

Required CSP Directives

Add the following origins to your Content Security Policy to allow the Pollenate widget to function correctly:

Example: HTTP Header

If you set your CSP via an HTTP response header, add the Pollenate origins to the relevant directives:

Content-Security-Policy: 
  script-src 'self' https://pollenate.dev; 
  connect-src 'self' https://api.pollenate.dev; 
  style-src 'self' 'unsafe-inline';

Example: HTML Meta Tag

If you set your CSP via a <meta> tag, include the Pollenate origins:

<meta http-equiv="Content-Security-Policy" content="
  script-src 'self' https://pollenate.dev; 
  connect-src 'self' https://api.pollenate.dev; 
  style-src 'self' 'unsafe-inline';
">

Example: Nginx

add_header Content-Security-Policy "
  script-src 'self' https://pollenate.dev; 
  connect-src 'self' https://api.pollenate.dev; 
  style-src 'self' 'unsafe-inline';
" always;

Example: Apache

Header set Content-Security-Policy "  script-src 'self' https://pollenate.dev;   connect-src 'self' https://api.pollenate.dev;   style-src 'self' 'unsafe-inline';"

Example: Next.js

In your next.config.js:

const securityHeaders = [
  {
    key: 'Content-Security-Policy',
    value: [
      "script-src 'self' https://pollenate.dev",
      "connect-src 'self' https://api.pollenate.dev",
      "style-src 'self' 'unsafe-inline'",
    ].join('; '),
  },
];

module.exports = {
  async headers() {
    return [{ source: '/(.*)', headers: securityHeaders }];
  },
};