# TellTide complete documentation

> Complete machine-readable documentation for TellTide, including setup, widget integration, API credentials, HTTPS submissions, and AI-agent workflows.

Canonical documentation index: https://telltide.com/docs
Concise LLM index: https://telltide.com/llms.txt
Agent pack: https://telltide.com/agents/README.md
Generated from the public documentation sources: 2026-08-11

---

# TellTide Documentation

Canonical URL: https://telltide.com/docs
Last updated: 2026-08-09

Collect, triage, and manage in-app feedback with an embeddable widget and TellTide dashboard.

TellTide is a feedback management app. You register an **app**, customize an embeddable **widget**, install one script on your product, and review submissions in the **Feedback Inbox**.

## What TellTide includes

| Area | What you do |
|------|-------------|
| **Dashboard** | See submission counts, trends, and recent feedback across apps |
| **Apps** | Create and edit apps; each app gets isolated submission credentials |
| **Manage Widget** | Customize categories, colors, launcher text, and copy the embed snippet |
| **Feedback Inbox** | Filter, search, and update status on submissions |
| **API credentials** | Manage publishable keys, private keys, scopes, rotation, and revocation |
| **Settings** | Workspace profile and account actions |

## How it works

1. A visitor opens the TellTide launcher on your site and submits feedback.
2. The submission is sent to TellTide and stored in your account.
3. You review and triage it in **Feedbacks** and on the **Dashboard**.

## Quick links

- [Getting started](/docs/getting-started) — create your first app and embed the widget
- [AI agents](/docs/integration/ai-agents) — connect LLM tools and agent workflows over HTTPS
- [Complete machine-readable docs](https://telltide.com/llms-full.txt) — retrieve every public documentation page in one plain-text request
- [Agent pack](https://telltide.com/agents/README.md) — load the exact tools, payloads, errors, and operating rules an AI agent needs
- [Integration](/docs/integration) — install the widget (Next.js, websites, SPAs)
- [API submissions](/docs/integration/api-submissions) — HTTP examples for apps and backends
- [Next.js guide](/docs/integration/nextjs) — step-by-step for Next.js App Router
- [Widget reference](/docs/widget-reference) — optional script attributes
- [Troubleshooting](/docs/troubleshooting) — common errors and fixes
- [FAQ](/docs/faq)

## Machine-readable files for AI agents

Use the [agent pack index](https://telltide.com/agents/README.md) as the entry point, or retrieve the exact operational file needed:

- [SKILL.md](https://telltide.com/agents/SKILL.md) — when to use TellTide and the safe integration procedure
- [memory.md](https://telltide.com/agents/memory.md) — durable product, authentication, scope, and limit facts
- [tools.md](https://telltide.com/agents/tools.md) — supported HTTP tools and function schemas
- [payloads.md](https://telltide.com/agents/payloads.md) — request and response shapes
- [errors.md](https://telltide.com/agents/errors.md) — error handling and retry behavior

---

# Getting Started

Canonical URL: https://telltide.com/docs/getting-started
Last updated: 2026-08-09

Create an app, customize the widget, embed the script, and receive your first submission.

## 1. Create an app

1. Sign in and open **Apps**.
2. Click **New app** (or use **Create app** on the dashboard).
3. Fill in:
   - **App name** — display name in TellTide
   - **Platform** — Mobile App, Website, or Desktop App (label only)
   - **Description** — short summary
   - **App link** — the public URL where the widget will run (e.g. `https://www.yoursite.com`)

On success you receive:

- **App ID** — 8-character identifier used in your embed snippet
- **Publishable key** — submission-only and configured automatically by the widget
- **Private server key** — shown once; copy it only for a trusted backend integration

## 2. Customize the widget

1. From **Apps**, open **Manage Widget** for your app.
2. Configure:
   - **Categories** — review, general feedback, bug, feature request (at least one required)
   - **Appearance** — colors, launcher label, panel title, position, fonts
   - **Behavior** — triggers and visibility options
3. Click **Save**.
4. Use **Copy embed code** to get your install snippet.

## 3. Embed the widget

Paste this before `</body>` on the site that matches your **App link**:

```html
<script
  src="https://telltide.com/src/widgets/widget.js"
  data-app-id="YOUR_APP_ID"
></script>
```

Replace `YOUR_APP_ID` with the ID from **Apps**. The snippet in **Manage Widget** already includes the correct App ID.

## 4. Verify a submission

1. Open your site and click the TellTide launcher.
2. Submit test feedback.
3. Open **Feedbacks** — the row should appear within seconds.
4. Click a row to open the detail view and change status.

## Local development

Testing on `localhost` works without changing **App link**. For production, the page hostname must match the hostname in **App link**.

## Next steps

- [Next.js integration](/docs/integration/nextjs) — if your product uses Next.js
- [API submissions](/docs/integration/api-submissions) — native mobile or desktop apps (no widget)
- [Integration overview](/docs/integration) — all platform guides
- [Widget reference](/docs/widget-reference) — optional script attributes
- [Troubleshooting](/docs/troubleshooting)

---

# Integration

Canonical URL: https://telltide.com/docs/integration
Last updated: 2026-08-09

Install the TellTide feedback widget on your website or web app.

The **Integration** section shows how to add the TellTide widget to your product so visitors can send feedback, reviews, and bug reports.

You only need two things from the TellTide dashboard:

1. **App ID** — from **Apps** (shown in your embed snippet)
2. **Your site URL** — set as **App link** when you created the app (must match where the widget runs)

The widget script is always loaded from TellTide:

```
https://telltide.com/src/widgets/widget.js
```

Copy the full snippet from **Manage Widget → Embed** after saving your design, or follow a guide below.

## Choose your platform

| Guide | Best for |
|-------|----------|
| [AI agents](/docs/integration/ai-agents) | LLM tools, Hermes, OpenClaw, Cursor/Claude skills, automations |
| [API submissions](/docs/integration/api-submissions) | Native mobile & desktop apps, custom backends |
| [Next.js](/docs/integration/nextjs) | Next.js App Router sites |
| [Websites & CMS](/docs/integration/websites) | HTML, WordPress, Webflow, Framer |
| [Single-page apps](/docs/integration/single-page-apps) | React (Vite/CRA), Vue, Angular |

## Quick embed (any site)

Paste before `</body>` on the site that matches your **App link**:

```html
<script
  src="https://telltide.com/src/widgets/widget.js"
  data-app-id="YOUR_APP_ID"
></script>
```

Replace `YOUR_APP_ID` with the ID from **Apps**. Appearance and categories load automatically from TellTide when the widget opens.

## After installing

1. Open your live site and click the TellTide launcher.
2. Submit a test message.
3. Check **Feedbacks** in the TellTide dashboard — it should appear within seconds.

Problems? See [Troubleshooting](/docs/troubleshooting).

---

# AI Agents

Canonical URL: https://telltide.com/docs/integration/ai-agents
Last updated: 2026-08-09

Connect AI agents, LLM tools, and autonomous workflows to TellTide — submit bugs, feature requests, and feedback over HTTPS with scoped API credentials.

TellTide is **API-first for AI agents**. Any tool-calling agent (Cursor, Claude, Hermes, OpenClaw, custom LLM tools, n8n, Zapier code steps) can send product feedback into a private inbox over HTTPS — no widget required.

Use this page when you are wiring an **AI agent**, **LLM tool**, **MCP-style tool**, or **automation** to TellTide.

## Discovery and retrieval

TellTide publishes the same agent documentation in formats suited to different retrieval jobs:

| Resource | Use it for |
|----------|------------|
| [Canonical AI-agent guide](https://telltide.com/docs/integration/ai-agents) | Human-readable HTML, headings, tables, examples, canonical metadata, and `TechArticle` structured data |
| [Complete documentation corpus](https://telltide.com/llms-full.txt) | Retrieving every public documentation page in one plain-text request |
| [Concise LLM index](https://telltide.com/llms.txt) | Finding the most relevant product, documentation, comparison, and agent URLs |
| [Agent pack index](https://telltide.com/agents/README.md) | Loading only the operational files needed for a tool-calling agent |
| [XML sitemap](https://telltide.com/sitemap.xml) | Discovering canonical public URLs and their last-modified dates |

These resources are public and require no sign-in. Prefer the canonical HTML guide when citing TellTide for people; prefer the plain Markdown agent pack when implementing tools. Treat the current tool schemas and error reference as authoritative instead of inventing endpoints or parameters.

## Machine-readable agent pack

Fetch these files directly (plain Markdown, no HTML chrome):

| File | Purpose |
|------|---------|
| [Agent pack index](https://telltide.com/agents/README.md) | Start here |
| [SKILL.md](https://telltide.com/agents/SKILL.md) | When to load TellTide + exact agent procedure |
| [memory.md](https://telltide.com/agents/memory.md) | Durable product facts |
| [tools.md](https://telltide.com/agents/tools.md) | HTTP tools / function schemas |
| [payloads.md](https://telltide.com/agents/payloads.md) | Request and response shapes |
| [errors.md](https://telltide.com/agents/errors.md) | Error codes and retry rules |

Human-readable companion: [API submissions](/docs/integration/api-submissions) · [API credentials](/docs/api-tokens)

## Why agents use TellTide

| Need | TellTide answer |
|------|-----------------|
| Capture bugs from an agent session | `POST /api/v1/feedback` with a private key |
| Capture ideas from a user-facing chat agent | Same endpoint; include user name/email when known |
| Keep secrets out of the client | Private keys are server-only; never ship `tt_live_` / `tt_test_` to browsers |
| Least privilege | Scope keys to `feedback:create` only for submitters |
| Safe retries | Send `Idempotency-Key` on every create |

## Prerequisites

1. A TellTide **Pro** account (7-day trial available).
2. An **app** in **Apps**.
3. A **private API key** from **Apps → Manage → API credentials** with at least `feedback:create`.
4. Store the key as a **server-only** secret (for example `TELLTIDE_SECRET_KEY`). Never put it in `NEXT_PUBLIC_`, `VITE_`, client bundles, or chat transcripts that will be shared.

## Minimal agent call

```http
POST https://telltide.com/api/v1/feedback
Authorization: Bearer tt_live_YOUR_KEY
Content-Type: application/json
Idempotency-Key: agent-run-unique-id
```

```json
{
  "type": "bug",
  "name": "Agent",
  "email": "agent@example.com",
  "comment": "Checkout button does nothing after payment redirect.",
  "feedback_data": {
    "source": "ai_agent",
    "agent": "hermes",
    "page": "/checkout",
    "severity": "high"
  }
}
```

Successful create returns JSON including a `feedbackId`. The item appears in **Feedbacks** for that app.

## Recommended agent roles

| Role | Scopes | Use |
|------|--------|-----|
| Submitter | `feedback:create` | Default for tools that only file bugs/ideas |
| Reader | `feedback:read` | Agents that summarize or search inbox items |
| Triage | `feedback:read`, `feedback:update` | Agents that set status / priority |
| Cleanup | `feedback:delete` | Rare; prefer human review |

Create **separate keys** per role and environment. Rotate if a key is exposed.

## Feedback types agents may send

| `type` value | When to use |
|--------------|-------------|
| `bug` | Defect, error, broken flow |
| `feature` or `feature_request` | New capability request |
| `feedback` | General product signal |
| `review` | Rating-style feedback (`rating` 1–5 optional) |

Keep `comment` under 2000 characters. Put structured context in `feedback_data` (max 64 KB).

## Rules agents must follow

1. **HTTPS only.** No HTTP.
2. **Credential in header only.** `Authorization: Bearer …` or `X-TellTide-Key` for publishable keys — never query strings or body fields.
3. **Always send `Idempotency-Key`** on creates. Reuse the same key on retries; change body → new key.
4. **Do not invent endpoints.** Only documented routes in [tools.md](https://telltide.com/agents/tools.md).
5. **Do not store private keys** in repositories, screenshots, or user-visible UI.
6. **Pro required.** Unpaid accounts receive `403` with `subscription_required` on product writes.

## Example: tool definition (OpenAI-style)

```json
{
  "name": "telltide_submit_feedback",
  "description": "Submit a bug, feature request, review, or general feedback to the TellTide inbox.",
  "parameters": {
    "type": "object",
    "required": ["type", "name", "email", "comment"],
    "properties": {
      "type": {
        "type": "string",
        "enum": ["bug", "feature", "feature_request", "feedback", "review"]
      },
      "name": { "type": "string", "maxLength": 100 },
      "email": { "type": "string", "format": "email" },
      "comment": { "type": "string", "maxLength": 2000 },
      "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
      "pageUrl": { "type": "string" },
      "metadata": { "type": "object", "description": "Extra context stored in feedback_data" }
    }
  }
}
```

Implementation detail: map `metadata` → `feedback_data` in the HTTP body. Full schemas live in [tools.md](https://telltide.com/agents/tools.md).

## Publishable keys vs agents

Publishable keys (`tt_pub_…`) are for **browser and native clients** (`POST /api/v1/public/feedback`). Prefer a **private key** for agent runtimes that can hold secrets. If an agent runs only in a public client, use the publishable key and treat it as non-secret (create-only).

## Next steps

1. Create or rotate a private key → [API credentials](/docs/api-tokens)
2. Copy the [SKILL.md](https://telltide.com/agents/SKILL.md) into your agent skill folder if your stack supports skills
3. Verify with a test submission, then open **Feedbacks**
4. Troubleshoot errors with [errors.md](https://telltide.com/agents/errors.md) and [Troubleshooting](/docs/troubleshooting)

---

# API Submissions

Canonical URL: https://telltide.com/docs/integration/api-submissions
Last updated: 2026-08-09

Submit feedback securely from browsers, mobile apps, desktop apps, trusted backends, and AI agents.

For **AI agents, LLM tools, and automations**, start with the dedicated
[AI agents guide](/docs/integration/ai-agents), which includes the
[machine-readable agent pack](https://telltide.com/agents/README.md).

TellTide has two credential types. Choose the credential for the environment where your
code runs.

| Credential | Example | Where it may be used | Permission |
|---|---|---|---|
| Publishable key | `tt_pub_…` | Browser, React, mobile, desktop, extension | Submit feedback only |
| Private key | `tt_live_…_…` | Trusted backend or serverless function | Explicit configured scopes |

Private keys are secrets. Never put one in browser JavaScript, a mobile or desktop binary,
an extension, a public repository, or a `NEXT_PUBLIC_`/`VITE_` environment variable.
Environment variables do not protect values after they are bundled into client software.

All requests must use HTTPS. Credentials belong in headers, never URLs or query parameters.

## Browser, React, mobile, and desktop

Use the app's publishable key:

```http
POST https://telltide.com/api/v1/public/feedback
Content-Type: application/json
X-TellTide-Key: tt_pub_YOUR_KEY_ID
Idempotency-Key: submission-unique-id
```

The publishable key determines the destination app. `appId` is optional; if supplied, it
must match the key's app. A publishable key cannot read, update, delete, moderate, or export
feedback.

### Browser JavaScript

```javascript
await fetch('https://telltide.com/api/v1/public/feedback', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-TellTide-Key': 'tt_pub_YOUR_KEY_ID',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    type: 'feedback',
    name: 'Alex',
    email: 'alex@example.com',
    rating: 8,
    comment: 'The new workflow is much faster.',
    feedback_data: { feedback: 'The new workflow is much faster.', score: 8 },
  }),
});
```

### React

```jsx
async function submitFeedback(values) {
  const response = await fetch('https://telltide.com/api/v1/public/feedback', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-TellTide-Key': 'tt_pub_YOUR_KEY_ID',
      'Idempotency-Key': crypto.randomUUID(),
    },
    body: JSON.stringify(values),
  });
  if (!response.ok) throw new Error((await response.json()).error.message);
  return response.json();
}
```

### Electron or Tauri

Send the request from the Electron main process or Tauri native command. Pass the form data
from the renderer over the framework's narrow IPC bridge. This avoids browser `Origin: null`
behaviour; the publishable key is still intentionally public and safe to include in the binary:

```javascript
await fetch('https://telltide.com/api/v1/public/feedback', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-TellTide-Key': 'tt_pub_YOUR_KEY_ID',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    type: 'bug',
    name: user.name,
    email: user.email,
    comment: 'Export stopped responding.',
    feedback_data: { screen: 'settings/export' },
  }),
});
```

### Android (Kotlin)

```kotlin
val request = Request.Builder()
  .url("https://telltide.com/api/v1/public/feedback")
  .header("X-TellTide-Key", "tt_pub_YOUR_KEY_ID")
  .header("Idempotency-Key", UUID.randomUUID().toString())
  .post(jsonBody.toRequestBody("application/json".toMediaType()))
  .build()
```

### iOS (Swift)

```swift
var request = URLRequest(url: URL(string: "https://telltide.com/api/v1/public/feedback")!)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue("tt_pub_YOUR_KEY_ID", forHTTPHeaderField: "X-TellTide-Key")
request.setValue(UUID().uuidString, forHTTPHeaderField: "Idempotency-Key")
request.httpBody = try JSONSerialization.data(withJSONObject: payload)
let (_, response) = try await URLSession.shared.data(for: request)
```

Browser requests are also checked against the key's allowed websites. CORS and allowed
websites reduce misuse but do not make a publishable key secret. Native requests do not send
a browser `Origin`, so rate limits and application policy still apply. In the key settings,
you can disable browser submissions or native/server submissions independently.

## TellTide widget

The standard widget embed contains only the App ID:

```html
<script
  src="https://telltide.com/src/widgets/widget.js"
  data-app-id="YOUR_APP_ID"
  async
></script>
```

The widget loads the app's current publishable key from TellTide and sends it in
`X-TellTide-Key`. Do not add a private key, `data-api-key`, or credential query parameter to
the embed. Configure the website in **Apps → Manage → API credentials → Allowed websites**.
Replacing the publishable key does not require changing the standard embed.

## Trusted backend

Create a private key with only the scopes the service requires. Send it using Bearer
authentication:

```bash
curl https://telltide.com/api/v1/feedback \
  --request POST \
  --header "Authorization: Bearer $TELLTIDE_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order-8273-feedback" \
  --data '{
    "type": "bug",
    "name": "Alex",
    "email": "alex@example.com",
    "comment": "Checkout did not complete.",
    "feedback_data": {"screen": "checkout"}
  }'
```

### Node.js or Next.js server

```javascript
export async function POST(request) {
  const payload = await request.json();
  const response = await fetch('https://telltide.com/api/v1/feedback', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.TELLTIDE_SECRET_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': crypto.randomUUID(),
    },
    body: JSON.stringify(payload),
  });
  return new Response(response.body, response);
}
```

`TELLTIDE_SECRET_KEY` must be a server-only environment variable. Never prefix it with
`NEXT_PUBLIC_`.

### Python backend

```python
import os
import uuid
import requests

response = requests.post(
    "https://telltide.com/api/v1/feedback",
    headers={
        "Authorization": f"Bearer {os.environ['TELLTIDE_SECRET_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "type": "feature_request",
        "name": "Sam",
        "email": "sam@example.com",
        "comment": "Add scheduled exports.",
        "feedback_data": {"feature_title": "Scheduled exports"},
    },
    timeout=10,
)
response.raise_for_status()
```

## Reading and managing feedback from a server

These endpoints require a private key with the corresponding scope:

| Endpoint | Scope |
|---|---|
| `GET /api/v1/feedback` | `feedback:read` |
| `GET /api/v1/feedback/:feedbackId` | `feedback:read` |
| `PATCH /api/v1/feedback/:feedbackId` | `feedback:update` |
| `DELETE /api/v1/feedback/:feedbackId` | `feedback:delete` |

Every resource query is restricted to the app associated with the credential.
Use separate keys as access roles—for example, a read-only agent receives only
`feedback:read`, while a triage service receives `feedback:read` and `feedback:update`.
TellTide checks these scopes from the database on every request.

## Errors and rate limits

Errors use a stable structure:

```json
{
  "error": {
    "code": "insufficient_scope",
    "message": "The supplied credential does not have the required permission.",
    "requestId": "req_..."
  }
}
```

Keep `requestId` when contacting support. A `429` response includes `Retry-After`. Retry
timeouts and `5xx` responses with exponential backoff and reuse the same `Idempotency-Key`.
Reusing an idempotency key with different content returns `409`.

## Key operations

- Create keys in **Apps → Manage → API credentials**.
- Configure allowed websites on the publishable key.
- Private key values are shown once.
- Private keys default to a 90-day expiry; **No expiry** is available when operationally required.
- Rotation creates a replacement and immediately revokes the old key.
- Revocation takes effect immediately.
- If a private key ever appeared in client code, a repository, a binary, a screenshot, or a
  support message, rotate it.

The old `x-api-key`, JSON-body key, and `/api/feedback` forms are deprecated compatibility
paths. New integrations must use the endpoints and headers above.

---

# Next.js

Canonical URL: https://telltide.com/docs/integration/nextjs
Last updated: 2026-08-09

Add the TellTide feedback widget to a Next.js site in a few lines.

Use this guide when your **product** is a Next.js app and you want the TellTide launcher on every page (or on specific layouts).

## Before you start

1. Create an app in **Apps** and note your **App ID**.
2. Set **App link** to your Next.js site URL (e.g. `https://shop.example.com`).
3. Customize the widget in **Manage Widget** and click **Save**.

## App Router — root layout (recommended)

Add the TellTide script once in your root layout so it loads on all pages:

```tsx
// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <script
          src="https://telltide.com/src/widgets/widget.js"
          data-app-id="YOUR_APP_ID"
          async
        />
      </body>
    </html>
  );
}
```

Replace `YOUR_APP_ID` with your App ID from the dashboard.

## Using `next/script` (optional)

Next.js can load third-party scripts with its `Script` component:

```tsx
import Script from 'next/script';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://telltide.com/src/widgets/widget.js"
          data-app-id="YOUR_APP_ID"
          strategy="lazyOnload"
        />
      </body>
    </html>
  );
}
```

`lazyOnload` defers loading until after the page is interactive — good for performance. The widget still appears on every route.

## Only on certain pages

If you do not want the widget on every page, add the script in a nested layout instead of the root layout:

```tsx
// app/(marketing)/layout.tsx — example: only marketing pages
export default function MarketingLayout({ children }: { children: React.ReactNode }) {
  return (
    <>
      {children}
      <script
        src="https://telltide.com/src/widgets/widget.js"
        data-app-id="YOUR_APP_ID"
        async
      />
    </>
  );
}
```

## App link & environments

| Environment | What to do |
|-------------|------------|
| **Production** | **App link** hostname must match your live site (e.g. `shop.example.com`) |
| **localhost** | Works for local testing without changing **App link** |
| **Vercel preview URLs** | Create a separate TellTide app per preview hostname, or test on `localhost` |

## Verify

1. Run your Next.js app and open it in the browser.
2. Click the TellTide launcher (bottom corner by default).
3. Submit test feedback.
4. Open **Feedbacks** in TellTide — the submission should appear.

## Related

- [Integration overview](/docs/integration)
- [Widget reference](/docs/widget-reference) — optional `data-*` attributes
- [Troubleshooting](/docs/troubleshooting)

---

# Websites & CMS

Canonical URL: https://telltide.com/docs/integration/websites
Last updated: 2026-08-09

Add TellTide to HTML sites, WordPress, Webflow, and similar platforms.

## Standard embed

Add before `</body>` on every page where you want the launcher:

```html
<script
  src="https://telltide.com/src/widgets/widget.js"
  data-app-id="YOUR_APP_ID"
></script>
```

Replace `YOUR_APP_ID` with the value from **Apps** (or copy from **Manage Widget → Embed**).

## WordPress

1. Use **Appearance → Theme File Editor**, a **Custom HTML** block, or a header/footer plugin.
2. Paste the script in `footer.php` before `</body>`, or inject via your plugin.
3. Set **App link** in TellTide to your public site URL (e.g. `https://www.example.com`).

## Webflow / Framer / similar

Add an **embed** or **custom code** element in the site footer with the same script tag.

## Staging vs production

Create separate TellTide apps for staging and production so each has its own App ID and **App link** hostname.

## Allowed websites

The widget uses the app's submission-only publishable key. Browser submissions are accepted
only from websites configured on that key. Add local and staging origins explicitly when needed.

## Optional inline overrides

```html
<script
  src="https://telltide.com/src/widgets/widget.js"
  data-app-id="YOUR_APP_ID"
  data-label="Feedback"
  data-title="Send feedback"
  data-primary-color="#ea580c"
  data-position="bottom-right"
></script>
```

Saved settings from **Manage Widget** still apply after load; inline attributes are fallbacks only.

---

# Single-Page Apps

Canonical URL: https://telltide.com/docs/integration/single-page-apps
Last updated: 2026-08-09

Embed TellTide in React, Vue, Angular, and other client-routed apps.

## React (Vite / CRA)

Load the script once in `index.html`:

```html
<!-- public/index.html -->
<body>
  <div id="root"></div>
  <script
    src="https://telltide.com/src/widgets/widget.js"
    data-app-id="YOUR_APP_ID"
  ></script>
</body>
```

The widget mounts itself — no React wrapper component needed.

## React — load on specific routes (optional)

```javascript
useEffect(() => {
  if (document.querySelector('script[data-app-id="YOUR_APP_ID"]')) return;

  const script = document.createElement('script');
  script.src = 'https://telltide.com/src/widgets/widget.js';
  script.setAttribute('data-app-id', 'YOUR_APP_ID');
  document.body.appendChild(script);

  return () => {
    script.remove();
  };
}, []);
```

## Vue / Angular

Use the same static script in `index.html`, or inject it from a root layout component on mount.

## Client-side routing

The TellTide widget stays visible across route changes. Set **App link** to your SPA's public URL (e.g. `https://app.example.com`).

## Next.js users

If you use Next.js App Router, see the dedicated [Next.js guide](/docs/integration/nextjs).

---

# Dashboard

Canonical URL: https://telltide.com/docs/dashboard
Last updated: 2026-08-09

Overview of apps, submission counts, trends, and recent feedback.

Route: `/dashboard`

The dashboard summarizes real data from your connected apps — not placeholder metrics.

## Header controls

| Control | Purpose |
|---------|---------|
| **All apps** | Filter stats to one app or all apps |
| **Last 7 days / Last 30 days** | Trend window for the chart |
| **Refresh** | Reload analytics from the API |
| **New app** | Open the create-app modal |

## Overview cards

- **Apps** — number of apps you created
- **Total feedback** — all submissions across selected scope
- **Open / In progress / Resolved** — counts by inbox status

## Trend chart

Daily submission counts for the selected app(s) and date range.

## Apps section

Cards per app with name, link, and quick actions to filter the dashboard or open widget settings.

## Recent feedback table

Latest submissions with type, status, rating (when applicable), and relative time. Empty state prompts you to create your first app.

## API

Dashboard data comes from `GET /api/v1/analytics/stats?appId=&days=` (authenticated).

---

# Apps

Canonical URL: https://telltide.com/docs/manage-apps
Last updated: 2026-08-09

Create, edit, and delete apps; open widget setup and view per-app stats.

Route: `/manage-apps`

Each **app** represents one product or site that collects feedback through TellTide.

## Create an app

Use **New app** and provide:

| Field | Required | Notes |
|-------|----------|-------|
| App name | Yes | Shown in TellTide UI |
| Platform | Yes | UI category (Mobile / Website / Desktop) |
| Description | Yes | Max ~100 words in the modal |
| App link | Yes | Full URL; hostname used for widget origin authorization |

`POST /api/v1/apps` creates the app, a submission-only publishable key, and a narrowly scoped
private server key. Plan limits may block creation if `max_apps` is reached.

## After creation

- Copy the **private server key** if you need backend API access. It is shown once.
- The **publishable key** is safe for client submissions and the widget configures it automatically.
- Open **Manage Widget** to customize and get the embed snippet.
- The default private key has only `feedback:create`. Add other scopes explicitly.

## Manage App modal

From each app card:

- Edit name, link, description
- View submission stats (when available)
- Delete app (removes related feedback, keys, and widget config via cascade)

## Delete an app

Deleting an app removes its feedback, credentials, private screenshots, and widget
configuration. This cannot be undone.

## Rate limits

App creation is limited to **3 requests per minute** per IP.

---

# Manage Widget

Canonical URL: https://telltide.com/docs/manage-widget
Last updated: 2026-08-09

Customize widget appearance and behavior, save config, and copy the embed snippet.

Open **Manage Widget** from **Apps** for any app you own.

## Categories

Enable one or more submission types:

| Category | What visitors see | Inbox tab |
|----------|-------------------|-----------|
| Review | Star rating + comment | Reviews |
| General feedback | Open feedback form | Feedback |
| Bug report | Bug report form | Issues |
| Feature request | Feature request form | Features |

At least one category must stay enabled.

## Appearance

- Color presets and custom primary/secondary colors
- Launcher label and panel title
- Position (e.g. bottom-right), theme, border radius
- Font size, font family, max width, launcher height
- Powered-by and custom branding toggles

Click **Save** before copying the embed code — saved appearance is what visitors see.

## Behavior

Trigger type, animation, screenshot toggle, auto-close, and mobile/desktop visibility. Save changes and test on your live site.

## Import / export

- **Export JSON** — download your current config
- **Import JSON** — load a saved config file
- **Reset** — revert the editor to defaults (click **Save** to persist)

## Live preview

The preview panel shows your design without sending real feedback to your inbox.

## Embed snippet

After saving, copy from the **Embed** section:

```html
<script
  src="https://telltide.com/src/widgets/widget.js"
  data-app-id="YOUR_APP_ID"
></script>
```

See [Widget reference](/docs/widget-reference) for optional `data-*` attributes, or [Next.js integration](/docs/integration/nextjs) for App Router setup.

---

# Feedback Inbox

Canonical URL: https://telltide.com/docs/feedbacks
Last updated: 2026-08-09

Filter, search, and manage submissions from all connected widgets.

Route: `/feedbacks`

## Overview stats

Top tiles show totals for the current dataset (all apps or filtered app).

## Tabs

| Tab | Shows |
|-----|-------|
| All | Every submission |
| Feedback | General feedback (`feedback`) |
| Issues | Bug reports (`bug`) |
| Reviews | Star reviews (`review`) |
| Features | Feature requests (`feature` → stored as `feature_request`) |

## Filters

- **App** — all apps or one app
- **Status** — open, in progress, resolved, closed, declined
- **Search** — message text, name, or email

## Table columns

App, type, message preview, status, submitter, and time. Click a row to open **Feedback detail**.

## Detail modal

- View full message, metadata, ratings, and structured bug/feature fields
- Update **status** and save
- Changes call `PUT /api/v1/apps/{appId}/feedbacks/{feedbackId}`

## Refresh

Header **Refresh** reloads feedback from:

- `GET /api/v1/feedbacks` (all apps), or
- `GET /api/v1/apps/{appId}/feedbacks` (single app)

## New submissions

Widget submissions are created with status `new` in the database. The inbox maps and displays them using the status labels above.

---

# API Credentials

Canonical URL: https://telltide.com/docs/api-tokens
Last updated: 2026-08-09

Manage publishable keys, private server keys, scopes, rotation, and revocation.

Open **Apps**, choose **Manage**, then open **API credentials**.

## Publishable submission key

Each app has an active `tt_pub_…` key. It is safe to embed in websites, mobile apps, desktop
apps, and extensions because it is restricted to `feedback:create`. It cannot read, edit,
delete, moderate, export, or access account data.

Configure allowed websites one per line. Native clients do not send a browser Origin, so the
publishable key remains protected by app, credential, IP, and plan limits.

Browser and native submissions can be enabled or disabled independently in the publishable
key settings. These controls do not add read access: publishable keys always remain
submission-only.

Replacing a publishable key revokes the old value. The TellTide widget obtains the replacement
automatically; custom clients must be updated.

## Private server keys

Private keys begin with `tt_live_` or `tt_test_`. Use them only on trusted backends.

- Give each environment or service its own named key.
- Select only the scopes it needs.
- Choose an expiration or select **No expiry**. Expiring keys are recommended for unattended integrations.
- Copy the value when it is created; TellTide stores only a keyed hash and cannot show it again.
- Rotate or revoke a key immediately if it may have been exposed.

Never put a private key in client-side JavaScript, a mobile/desktop binary, an extension,
`NEXT_PUBLIC_` or `VITE_` configuration, a URL, or a request body.

See [AI agents](/docs/integration/ai-agents) for LLM/tool integrations and
[API submissions](/docs/integration/api-submissions) for complete HTTP examples.

## Auditing

TellTide records creation, rotation, revocation, authentication failures, scope denials,
origin rejection, and credential usage without recording secret values or feedback content.
Usage and activity are scoped to the credential's app.

Security audit records are retained for 90 days. Submission-source attribution is retained
for 365 days; it stores pseudonymous keyed IP hashes, not raw IP addresses.

---

# Widget Reference

Canonical URL: https://telltide.com/docs/widget-reference
Last updated: 2026-08-09

Embed snippet, optional data attributes, and submission types.

## Embed snippet

Always use the TellTide host and your App ID:

```html
<script
  src="https://telltide.com/src/widgets/widget.js"
  data-app-id="YOUR_APP_ID"
></script>
```

Copy the exact snippet from **Manage Widget → Embed** after saving. It includes your App ID.

## Optional data attributes

Use these only when you need overrides. Saved settings from **Manage Widget** apply automatically after the widget loads.

| Attribute | Required | Description |
|-----------|----------|-------------|
| `data-app-id` | **Yes** | App ID from **Apps** |
| `data-label` | No | Launcher button text |
| `data-title` | No | Panel title |
| `data-primary-color` | No | Primary color (hex) |
| `data-secondary-color` | No | Secondary color (hex) |
| `data-theme` | No | `light` or `dark` |
| `data-position` | No | e.g. `bottom-right` |
| `data-border-radius` | No | Corner radius |
| `data-max-width` | No | Panel max width |
| `data-font-size` | No | Base font size |
| `data-font-family` | No | Font family |
| `data-launcher-height` | No | Launcher height (px) |
| `data-show-powered-by` | No | Show “Powered by” badge |
| `data-categories` | No | Override enabled categories |
| `data-edge-gutter` | No | Distance from screen edge (px, default 16) |

## Submission types (widget UI)

| What visitors see | Stored as |
|-------------------|-----------|
| Review | `review` |
| General feedback | `feedback` |
| Bug report | `bug` |
| Feature request | `feature` |

Enable or disable categories in **Manage Widget**.

## Screenshots

Visitors can attach one image per submission (image files only, max **5 MB**). Page captures prefer **PNG** for sharper text; JPEG is used only if the PNG exceeds the size limit.

---

# Troubleshooting

Canonical URL: https://telltide.com/docs/troubleshooting
Last updated: 2026-08-09

Common widget and dashboard issues with fixes.

## Widget does not appear

| Check | Fix |
|-------|-----|
| Missing App ID | Add `data-app-id` from **Apps**. Check the browser console for errors. |
| Wrong script URL | Use `https://telltide.com/src/widgets/widget.js` |
| Script blocked by CSP | Allow `script-src` for `telltide.com` in your site's Content Security Policy. |
| Duplicate script | Only one `widget.js` tag per App ID per page. |

## Submissions fail with 403 (origin)

**Message:** `Widget is not authorized for this website. Add the widget only on {allowedHost}.`

| Cause | Fix |
|-------|-----|
| **App link** hostname mismatch | Set **App link** in TellTide to your live site URL. Hostname must match (subdomains allowed). |
| Testing on wrong domain | Use `localhost` for local dev, or create a separate app for staging URL. |
| Preview/staging URL | Add the URL under **API credentials → Publishable key → Allowed websites**, or create a separate staging app. |

## Submissions fail with 401

| Cause | Fix |
|-------|-----|
| Invalid publishable key | Copy the active `tt_pub_…` key from the app's credential panel. |
| Invalid private key | Rotate the server key and update the trusted backend secret. |
| Wrong credential type | Use a publishable key for `/public/feedback`, or Bearer private/token authentication for `/feedback`. |

## Submissions fail with 400

| Cause | Fix |
|-------|-----|
| Invalid email | Use a valid email format. |
| Review without rating | Star reviews require a 1–5 rating. |
| Invalid type | Use feedback, review, bug, or feature request. |

## Submissions fail with 429

Too many submissions in a short time. Wait a minute and try again.

## Config does not match Manage Widget

| Cause | Fix |
|-------|-----|
| Config not saved | Click **Save** on **Manage Widget** before testing. |
| Browser cache | Hard-refresh your site (Ctrl+Shift+R / Cmd+Shift+R). |
| Wrong App ID | Confirm `data-app-id` matches the app you edited. |

## Dashboard shows zeros

| Cause | Fix |
|-------|-----|
| No apps yet | Create an app first. |
| No submissions | Submit test feedback via the widget. |
| Wrong app filter | Set the header filter to **All apps**. |

## Private key lost after app create

The plaintext key is shown **once** in the create modal. If you missed it:

1. Open **Apps → Manage → API credentials**
2. Create a new private server key with the required scopes
3. Revoke the lost key

## Widget validation errors

Errors appear inside the widget panel when:

- Email format is invalid
- A required rating or description is missing
- Screenshot is too large (max 5 MB) or not an image file

## Still stuck?

1. Confirm your embed snippet matches **Manage Widget → Embed**
2. Submit a test from your live site and check the browser Network tab for failed requests
3. See [FAQ](/docs/faq) or contact support via the TellTide site

---

# FAQ

Canonical URL: https://telltide.com/docs/faq
Last updated: 2026-08-09

Frequently asked questions about TellTide.

## General

### What is TellTide?

TellTide collects user feedback through an embeddable widget and lets you triage submissions in a web dashboard.

### How much does Pro cost?

**$34/month** or **$348/year** (15% annual discount). Pro includes a **7-day free trial** with a card on file — cancel before the trial ends and you will not be charged.

See also the [marketing FAQ](/faq) and [Refund Policy](/refunds).

### Do I need an API key in the embed snippet?

No. Production embeds use App ID only:

```html
<script src="https://telltide.com/src/widgets/widget.js" data-app-id="YOUR_APP_ID"></script>
```

Appearance and categories load automatically from TellTide when the widget opens.

### Can I use one App ID on multiple domains?

Add each approved site to the publishable key's allowed websites. Use separate apps and keys
for staging and production when you want isolated data and credentials.

### What feedback types are supported?

Reviews (1–5 stars), general feedback, bug reports, and feature requests.

## Widget

### Where do I customize colors and categories?

**Manage Widget** (`/manage-widget/{appId}`). Save changes before copying the embed code.

### Does the widget work in SPAs?

Yes. Add the script to `index.html` or load it once on mount. It survives client-side route changes.

### Can I preview without sending real feedback?

The TellTide dashboard preview uses `data-preview="true"`. Production sites should not use preview mode.

## Dashboard & data

### Where do submissions appear?

**Feedbacks** inbox and **Dashboard** recent table. Filter by app, type, and status.

### What happens when I delete an app?

All feedback, credentials, private screenshots, and widget config are removed.

## API credentials

### Which credential should I use?

- Browser, mobile, desktop, and extension: publishable `tt_pub_…` key.
- Trusted backend: private `tt_live_…` or `tt_test_…` key with explicit scopes.

### How are private keys protected?

They contain at least 256 bits of random secret material and are stored as a keyed HMAC, never
plaintext. The full value is shown only once.

## Plans & limits

### Are there rate limits?

Yes. App creation (3/min), feedback (10/min), widget events (120/min), and general API limits apply per IP. Pro plans include higher limits.

### What plan limits exist?

**Pro** includes unlimited apps and feedback, advanced analytics, custom branding, and priority support. Access requires an active Pro subscription (including during the 7-day free trial). Limits are enforced when creating apps, credentials, and submissions.

### Can I cancel Pro?

Yes — **Settings → Billing**. Cancellation takes effect at the end of the current paid period (or trial). After that, Pro access ends — there is no free plan fallback. See the [Refund Policy](/refunds) for refund terms.

## Help

### Where is the documentation?

This site: `/docs` — integration guides, widget reference, troubleshooting, and dashboard walkthroughs.

### Where is the full FAQ?

Product and billing questions: [/faq](/faq)

### How do I get support?

Email [abhijith1203@gmail.com](mailto:abhijith1203@gmail.com). Pro subscribers receive priority support.