Setup skill for coding agents
This page is written for a coding agent (Claude Code, Cursor, Codex, VS Code or any other) that has been asked to set up Telltale in an application. A person pastes one prompt from Connect your channels in the Telltale dashboard; the prompt points here and gives you the site's publishable key and the Telltale server's address. It never contains a server key.
Work in small steps, propose each change before you make it, and stop to ask when something below does not match the application.
1. Find out what kind of application this is
Look at the repository before you change anything:
- A website or web app people sign in to (React, Next.js, Vue, Nuxt, WordPress, Shopify, Webflow, plain HTML): add the browser tag (step 2), then identify signed-in users from the server (step 3).
- An MCP server: wrap it with Telltale for MCP servers (step 4).
- An HTTP API that agents call: add the API middleware (step 4).
Many products have more than one of these. Do the web app first.
2. Add the browser tag
Read https://app.trytelltale.dev/docs/quickstart.md and the guide for the framework you found (https://app.trytelltale.dev/docs/nextjs.md, react.md, wordpress.md, shopify.md, webflow.md or gtm.md). Use the publishable key from the prompt (ao_pk_...). It is public and safe in page code.
Ask the person one question before you add it: does the site show a cookie or consent banner? If it does, hold collection until consent (data-telltale-wait-for-consent on the tag, or waitForConsent: true) and connect the banner as in https://app.trytelltale.dev/docs/consent.md. If it does not, the tag records on page load.
If the site sends a Content Security Policy, follow https://app.trytelltale.dev/docs/csp.md. Never add unsafe-inline or unsafe-eval.
3. Tell Telltale who is signed in, from your server
After sign-in, your backend calls identify({sessionToken, userId, accountId}) with the server adapter (https://app.trytelltale.dev/docs/server.md). Use the application's own opaque IDs. Never send names, email addresses, passwords, cookies or anything a person typed.
The server key (ao_sk_...) belongs in the server's secret store or environment, never in page code and never in the repository. The person creates it in Settings › Channels. Ask them for it; do not invent one.
4. MCP servers and APIs
- MCP server: https://app.trytelltale.dev/docs/mcp.md. One wrapper; Telltale receives tool names, outcomes and timings, never arguments or results.
- API: https://app.trytelltale.dev/docs/api-channel.md. One middleware for Node http, Express, Next.js, Hono or Fastify.
Both use the server key from the environment and an identify hook that returns the account and user IDs your server already knows.
5. Check that it works
- Run the application locally or on a preview deployment and open a page with the tag.
- In the Telltale dashboard, Connect your channels › Is it working? ticks First session received and its heading turns to "It’s working" within a few seconds.
- If nothing arrives, read https://app.trytelltale.dev/docs/troubleshooting.md: the usual causes are an address that is not on the site's allowed list, a wrong key, waiting for consent, or a CSP block.
6. Report back
Tell the person what you changed, file by file, what you tested, and what you could not test (for example consent withdrawal or a production-only CSP). Leave the merge to them.
What never to do
- Never put the server key in browser code, a public repository or a log.
- Never collect typed content, credentials, cookies or request bodies for Telltale.
- Never treat a Telltale verdict as permission: protected actions still need your application's own authorization.
More: https://app.trytelltale.dev/llms.txt lists every page, and the docs MCP server at https://app.trytelltale.dev/mcp serves them on demand.