converly

Files (7)

• .gitignore
• LICENSE
• README.md
• SKILL.md
• destinations.md · references/
• rest-api.md · references/
• triggers.md · references/

SKILL.md (first lines)

# Converly: conversion tracking for AI agents

Converly tracks form submissions on a website and fires conversion events to ad platforms (Google Ads, Meta, GA4 and more), including server side delivery like Google Enhanced Conversions and Meta CAPI. You do the whole setup from the terminal with the `converly` CLI, verify it works with a real test event, and read conversion results afterwards.

Every CLI command prints one JSON document to stdout. Exit code 0 means success. Errors are JSON on stderr with the API's error code.

## Hard rules (read first)

1. **Never handle credentials in chat.** Do not ask the user to paste an API key, and never print `CONVERLY_API_KEY` or any token. Authentication is `converly login`, which happens in the user's browser.
2. **Connecting an ad platform requires a human.** `converly destinations connect` returns a URL the user must open in their browser. Never claim a destination is connected until `converly handoffs wait <id>` returns `"status": "completed"`. Never skip this step, and never work around it by asking for tokens.
3. **Be precise about what is verified.** `converly test-event` returning `"server_status": "success"` proves the DELIVERY half: Converly can reach the ad platform and the platform accepted the conversion. `install status` showing `"detection": "confirmed"` proves the loader is on the page and running (it phones home on page load). Neither proves the form itself gets detected. Full proof of capture is a real form submission appearing in `converly events list` with a successful action status. Report exactly which level you verified. Publishing a flow proves nothing by itself.
4. **Never pass `--allow-real` without the user's explicit agreement in this conversation.** It reports a real conversion to their ad platform. Ask, wait for yes, then run it.
5. **Set the site's domain before publishing.** A site with `"domain": null` rejects every event server side. The flow will publish fine and capture nothing. Check `converly sites list` and fix with `converly sites update <site_id> --domain <their-domain>` before you publish.
6. **Destructive actions need explicit user confirmation first.** Deleting a flow (`flows delete` requires `--yes`), unpublishing a flow that is live, disconnecting a destination, or any DELETE via `converly api`. Never do these on your own initiative, even for things you created this session.
7. **If a command fails twice with the same error, stop and show the user the error.** Do not loop retries. If you must retry a create command after an ambiguous failure, re-run it with the same `--idempotency-key` value so it cannot double-create.
8. **Never choose the conversion for the user.** Always run `converly destinations conversions <destination>` first, whatever the platform. If it returns options, show them and ask which one this form represents. If it comes back empty or errors, ask the user what the conversion should be called rather than inventing one. A wrong conversion still reports success while quietly corrupting the numbers they are trying to collect. Google Ads can only fire conversion actions that already exist in their Google Ads account, so if none fit they create one there and you re-list with `--refresh`. Meta and GA4 take a standard event from the list, or a name of the user's own with `--custom`.

## The setup workflow

**Collect four facts before you build anything.** Answer them yourself
from the repo or page when you have access; otherwise ask the user, all
in one message rather than drip-feeding:

1. **The website address.** Without it every conversion is rejected
   server side (hard rule 5).
2. **Which tool renders the form** (or booking widget / chat box). This
   picks the trigger, decides which detection code loads on the site,
   and decides whether a connect step is needed first (step 3).
3. **What should count as the conversion.** If something must happen
   after submission before it really counts (email verification,
   payment, onboarding), a form trigger overcounts; use the `api`
   trigger instead and say why.
4. **Which ad platforms the conversions should go to.** Google Ads,
   Meta, GA4 and the rest. One flow can fire to several at once. You
   cannot pick a destination without this, and the conversion the user
   chooses in step 4 lives inside whichever platform they name.

Work through these steps in order.

### 1. Log in or create an account

Install the CLI if it is missing:

```
npm install -g @converly/cli
```

(Or run every command through `npx @converly/cli ...` without installing.)

Then check where you stand:

```
converly whoami
```

- If it succeeds, you are logged in. It returns the subscription and the account's sites.
- If it fails with `not_logged_in`, run `converly login` and tell the user a browser window will open for them to log in. If they do not have a Converly account yet, run `converly login --signup` instead. Signing up starts a free trial automatically, no card needed. Wait for the command to finish, then re-run `converly whoami`.
- On a server, in CI, or anywhere without a browser, use `converly login --device`. It prints a short code and a URL the user opens on any device (their phone is fine); they approve there and the CLI picks the credential up. The CLI selects this automatically when no browser is available.
- If `CONVERLY_API_KEY` is set in the environment, the CLI uses it automatically for Converly's own deployments. If commands then fail saying the key was rejected, the key is bad. Ask the user to replace or unset it; do not try to work around it.

At any point, `converly status` prints the ordered setup checklist for a site: what is done, what needs action, and the exact command for each. Run it whenever you are unsure what comes next.

### 2. Pick the site and set its domain

```
converly sites list
```

Every account has a default site. Use it unless the user is tracking a second website. If `domain` is null, set it now (hard rule 5):

```
converly sites update site_XXXX --domain example.com
```

Use the site's real public domain. One domain covers both the apex and its www variant.

### 3. Choose the trigger, and connect it if it needs connecting

The trigger is the form tool on the user's website. Get the catalogue:

```
converly triggers
```

Match the user's form tool to a slug in `providers[]` (for example `webflow-forms`, `gravity-forms`, `hubspot-forms`). For a hand coded HTML form use `generic-form`. If you have repo access, identify the form tool from the code instead of asking.

**Custom sites are the one case where `generic-form` is not automatically the right answer.** Detection is dependable for a known form tool, whose markup and submit behaviour Converly knows. A hand coded form on a Next.js, Astro, SvelteKit or Remix site varies far more, and many post to a backend route or server action rather than submitting the classic way. So when you are working in the site's code and the form posts to a backend, the `api` trigger is often more reliable. The backend confirms the conversion directly instead of relying on the browser catching a bespoke form, and you are already in the code, which is the part a human would find fiddly.

Put the call where the handler (route handler, server action, or whatever processes the submission) has confirmed the submission actually succeeded, not at the top of it. Every call to the webhook counts a conversion, so firing before validation would count failed and spam attempts too. Ask the user before editing their code.

Use `generic-form` when the form is genuinely simple, you do not have code access, or the user prefers no code changes.

**Check the provider's `setup` block before using its slug.** Most tools have `requires_connection: false` and their slug goes straight into `flows create`. A few (Typeform, Jotform, Calendly, Acuity Scheduling today, read the data, never a memorized list) have `requires_connection: true`. Those must be connected FIRST, or the flow tracks nothing properly:

```
converly triggers connect typeform --site site_XXXX
```

Give the user the returned `url` (they sign in to the tool there, or paste its API key), then confirm completion the same way as a destination:

```
converly handoffs wait hdf_XXXX
```

When the completed result lists anything in `user_steps_remaining`, the connection alone is NOT the whole setup. Relay each step to the user and treat setup as unfinished until they confirm it is done. Acuity is the standing example. Its bookings are only reported once the user pastes a tracking snippet inside Acuity's own settings (the connect window shows them the snippet). Converly cannot verify that step happened, so never report Acuity setup as complete on connection alone; the proof is the first booking appearing in `converly events list`.

The same honesty applies to `capture_without_connection` in the setup block. It tells you what actually happens if the user declines to connect (for example Typeform still reports bare submission counts but no visitor details, so ad platforms match poorly). Use it to explain tradeoffs truthfully, not to skip the connect step.

Once a connection-required platform is connected, you can narrow the flow to one specific form or event type instead of firing on all of them. List the account's real ones with `converly triggers options <slug> --site site_XXXX`, offer the user a specific value, and write it back as `trigger_config.conditions` (the full shape is in references/triggers.md → Filters). This is optional, an unfiltered flow is valid and publishable. Browser-detected form tools do not support this, narrow those by page with `--pages` instead.

Before choosing a trigger type at all, apply fact 3 from the interview. If there is a verification step, a payment, or onboarding between the form and the real outcome, a form trigger counts people who never converted; use the `api` trigger instead.

The `api` trigger has no form tool to detect, so its setup is different. Connect it with `converly triggers connect api --site site_XXXX`, which hands back a webhook URL and secret that the user's backend calls when the conversion is confirmed. For a Node backend, the `@converly/sdk-node` package does the signed call in a few lines (`npm install @converly/sdk-node`, then `createClient` and `completeSignup`). Other stacks call the webhook directly. The full backend guide is at developers.converly.io/api-trigger. This needs code access, so it suits agents working in the site's repo.

### 4. Connect the destination and choose the conversion

See what is available and what is already connected:

```

From converlyio/converly-agent, MIT-0.