Documentation — Telltab

⚡ Quick install

Add a single line before </body> on your website:

<script
  src="https://telltab.com/api/widget.js"
  data-site="my-site.com"></script>

That's it. The feedback button appears in the bottom-right corner. No dependencies, no cookies, zero configuration required.

🎯 First feedback

Once the widget is embedded:

Open your site in a browser
Click the purple button in the bottom-right corner
Pick a category, type a message, submit
The feedback appears immediately in the admin dashboard

⚙️ Widget options

All options are set through data-* attributes on the <script> tag:

Attribute	Default	Description
data-site	page hostname	Site identifier (used to filter feedback per project)
data-lang	`fr`	Widget language: `fr` or `en`
data-color	`#4F46E5`	Main color of the button and accents (hex)
data-position	`bottom-right`	Position: `bottom-right`, `bottom-left`, `top-right`, `top-left`
data-user	empty	Logged-in user identifier (e.g. ID or email) — used to know who submitted the feedback
data-site-token	empty	Site authentication token (optional, for secured configurations)
data-offset-x	`20`	Horizontal offset in px from the edge (left or right depending on `data-position`)
data-offset-y	`20`	Vertical offset in px from the edge (top or bottom depending on `data-position`)

🏷️ Categories

The widget ships with 5 standard categories to classify feedback:

Bug — malfunction, error, crash. Automatically enables technical metadata capture (user-agent, viewport, JS errors).
Idea — suggestion for a new feature
Improvement — suggestion on something existing
Feedback — general feedback
Feature — specific feature request

🌍 Languages

<!-- Widget in French (default) -->
<script src="https://telltab.com/api/widget.js"
  data-site="my-site.com"
  data-lang="fr"></script>

<!-- Widget in English -->
<script src="https://telltab.com/api/widget.js"
  data-site="my-site.com"
  data-lang="en"></script>

The language affects every UI string as well as voice recognition (fr-FR or en-US).

🎨 Appearance

<script
  src="https://telltab.com/api/widget.js"
  data-site="my-site.com"
  data-color="#E11D48"        <!-- red -->
  data-position="bottom-left"  <!-- bottom-left corner -->
></script>

📄 HTML integration

<!DOCTYPE html>
<html>
  <body>
    <!-- Your content -->

    <!-- Telltab widget — just before </body> -->
    <script
      src="https://telltab.com/api/widget.js"
      data-site="my-site.com"
      data-lang="en"
      data-color="#4F46E5"
      data-position="bottom-right"></script>
  </body>
</html>

⚛️ React / Next.js

// components/TelltabWidget.tsx
import Script from 'next/script'

export default function TelltabWidget() {
  return (
    <Script
      src="https://telltab.com/api/widget.js"
      data-site={process.env.NEXT_PUBLIC_SITE_ID}
      data-lang="en"
      data-color="#4F46E5"
      data-user={session?.user?.email ?? ''}
      strategy="lazyOnload"
    />
  )
}

Mount the component in your root layout (app/layout.tsx or _app.tsx). The data-user attribute ties each feedback to the logged-in user.

💚 Vue.js

// main.js or App.vue (mounted hook)
mounted() {
  const script = document.createElement('script')
  script.src = 'https://telltab.com/api/widget.js'
  script.setAttribute('data-site', 'my-site.com')
  script.setAttribute('data-lang', 'en')
  script.setAttribute('data-color', '#4F46E5')
  document.body.appendChild(script)
}

🖥️ Admin dashboard

The dashboard is available at:

https://telltab.com/admin

Available features:

Filter by site, category, status, date range (from/to), free text
Change the status of a feedback: New → In progress → Done → Rejected
Set the priority: Low / Medium / High / Critical
Add notes in the admin reply field
Delete individually or in bulk
Export to CSV with the active filters

The dashboard automatically detects your browser language (FR or EN).

🔔 Email notifications

Telltab automatically sends an email for every feedback with High or Critical priority. Configuration in .env:

NOTIFY_EMAIL=you@email.com
SMTP_HOST=your-smtp-server
SMTP_PORT=587
SMTP_USER=noreply@your-domain.com
SMTP_PASSWORD=password
SMTP_TLS=true   # false for internal relay without STARTTLS

🔗 Webhooks

Receive every new feedback in Slack, n8n, or any webhook-compatible service:

SITE_WEBHOOKS={"my-site.com":"https://hooks.slack.com/services/xxx","other-site":"https://n8n.xxx/webhook/yyy"}

Payload sent:

{
  "id": 42,
  "site": "my-site.com",
  "category": "bug",
  "priority": "critical",
  "message": "Crash on startup on Safari",
  "created_at": 1744143600,
  "dashboard_url": "https://telltab.com"
}

📥 CSV export

Export all your feedback (with optional filters) through the API:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://telltab.com/api/feedback/export?site=my-site.com" \
  -o feedbacks.csv

Supported parameters: site, category, status, date_from (YYYY-MM-DD), date_to, search.

🔌 REST API

All admin endpoints require the Authorization: Bearer TOKEN header.

Method	Endpoint	Description
GET	/api/feedback	List feedback (filters: site, category, status, search, date_from, date_to, limit, offset)
GET	/api/feedback/stats	Global statistics
PATCH	/api/feedback/{id}	Update status, priority or reply
DELETE	/api/feedback/{id}	Delete a feedback
DELETE	/api/feedback/bulk	Bulk delete (body: {"ids": [1,2,3]})
GET	/api/feedback/export	CSV export (same filters as list)
GET	/api/feedback/stats	Stats per category and per site
GET	/api/admin/weekly-summary	Weekly AI summary (VPN only)

🎙️ Voice feedback

The widget includes a dictation mode with automatic transcription. The user clicks "Dictate", speaks, then submits. The transcription runs server-side and is stored with the feedback.

Compatibility: Chrome, Edge, Safari 15+. Firefox partially supported. Real-time speech recognition (SpeechRecognition) requires HTTPS.

🐛 Enriched bug mode

When the Bug category is selected, the widget automatically captures:

Full browser user-agent
Window dimensions (viewport) and pixel ratio
Page URL and referrer
The last 5 JavaScript errors captured on the page

A 📷 button also lets the user capture a screenshot of the page at the time of the bug (html2canvas technology, loaded on demand).

🤖 Weekly AI summary

Get an intelligent summary of the week's feedback:

curl -H "X-Forwarded-For: 100.x.x.x" \  # from Tailscale VPN
  "http://172.20.0.107:3000/api/admin/weekly-summary"

The summary identifies recurring themes, critical bugs and suggests a priority action recommendation. Requires the LITELLM_URL environment variable to be configured.