Convolyn Docs — Embed, Configuration & Widget Reference

This reference covers how to embed the Convolyn widget, the configuration available on your bot, and how the pieces fit together. It's written for anyone comfortable pasting a script tag into a site — no advanced development required.

---

The embed snippet

Every Convolyn bot has a single embed snippet. Copy it from your bot's settings and paste it into your site's HTML, ideally just before the closing </body> tag:

<script src="https://convolyn.com/widget.js" data-chatbot-id="YOUR_BOT_ID"></script>

• src — always https://convolyn.com/widget.js. This loads the widget loader.
• data-chatbot-id — your bot's unique ID. This is what tells the widget which bot to load, which knowledge to use, and which branding to apply.

Once the script loads, the chat launcher appears on your page. No other code is required.

Where to put it

• Plain HTML site: before </body> on every page you want the widget.
• WordPress: use a "header/footer scripts" plugin, or add it to your theme's footer.
• Site builders (Webflow, Framer, etc.): add it to the site-wide custom code / footer section.
• React / Next.js: render the script tag in your root layout, or inject it once on mount.

---

What's configured in the dashboard (not in code)

Most of the widget's behavior is set in your bot's settings, not in the embed code — so you can change it without touching your site:

Because these live on the bot, updating them takes effect everywhere the snippet is embedded — no re-paste needed.

---

How answers work (RAG)

Convolyn uses retrieval-augmented generation:

1. You add knowledge sources (PDF, text, or website content).
2. Convolyn splits them into passages and creates embeddings.
3. When a visitor asks a question, Convolyn retrieves the most relevant passages.
4. The model answers using those passages, in your chosen response style.

If the answer isn't in your knowledge, the bot says so rather than inventing one. This is by design — it keeps answers grounded in your material.

---

Lead capture & delivery

When lead capture is enabled (Growth/Pro), and a conversation provides the required details:

• The lead is saved and visible in your dashboard.
• You receive an email notification with an AI-written summary.
• If a webhook URL is configured on the bot, Convolyn sends a POST with the lead data (works with Zapier, Make, n8n, or a custom endpoint).

Webhook payload

The webhook sends JSON shaped like this:

{
  "event": "lead.created",
  "lead": {
    "id": "…",
    "email": "…",
    "name": "…",
    "phone": "…",
    "company": "…",
    "custom_answers": { "Question?": "Answer" },
    "note": "AI-written conversation summary",
    "created_at": "ISO-8601 timestamp"
  },
  "chatbot": { "id": "…", "name": "…" },
  "conversation_id": "…"
}

The webhook fires once, when the lead is complete (or shortly after, for abandoned partial leads), so you won't get duplicate triggers.

---

Message limits

Each plan includes a monthly message allowance shared across all your bots. Limits count the bot's replies. If you reach your limit, bot responses pause until the next cycle or until you upgrade. There's no limit on the number of simultaneous visitors — only on total monthly messages.

---

Multiple bots & domains

• You can run multiple bots under one account (up to your plan's limit), each with its own knowledge, branding, and embed snippet.
• Use different bots for different sites or sections — each is identified by its own data-chatbot-id.

---

Quick troubleshooting

• Widget doesn't appear: confirm the snippet is on the page and the data-chatbot-id is correct; check the browser console for errors.
• Bot says "I don't know" too often: add or rewrite the relevant knowledge; check the analytics "unanswered questions" list.
• No lead notifications: confirm lead capture is enabled, your plan supports it (Growth/Pro), and the required fields are being collected.

---

Need something not covered here? Contact us and we'll help.