Web Embed quick start
Add Canopi to any website with a single script tag. Visitors get a trigger (corner tab or icon) that opens the full Canopi sidebar connected to your community.
Prerequisites
- A Canopi account at app.canopi.live
- A created embed instance with domain whitelist configured
- Ability to edit your site's
<head>or tag manager
Step 1 — Create an embed instance
- Sign in at app.canopi.live.
- Open My Canopis → Create embed.
- Set:
- Name — e.g. "Help Center"
- Community — which auth community connects
- Domain whitelist —
example.com,www.example.com - Page rules — URL patterns (e.g.
/help/*,/docs/*) - Trigger — corner tab position, message, colors
- Copy the generated embed code.
Step 2 — Add the script tag
Paste into your site <head> (or before </body>):
html
<script
src="https://app.canopi.live/embed/v1.js"
data-canopi-id="YOUR_INSTANCE_ID"
async
></script>Replace YOUR_INSTANCE_ID with the ID from the dashboard.
Step 3 — Verify
- Open a page matching your page rules on a whitelisted domain.
- Confirm the trigger appears (bottom-right by default).
- Click it — the sidebar should load and connect.
- Check browser devtools → Network for
GET /api/embeds/config/YOUR_INSTANCE_ID(200).
Optional: data attributes
| Attribute | Description |
|---|---|
data-canopi-id | Required. Embed instance ID |
data-pages | Comma-separated URL patterns (overrides server config if supported) |
data-trigger-position | bottom-right, bottom-left, etc. |
data-trigger-message | Hover text on the trigger tab |
Page targeting
Embed instances support pattern-based rules stored server-side:
json
{
"type": "patterns",
"patterns": ["/help/*", "/docs/*", "/blog/*"]
}The SDK evaluates the current path against these patterns before injecting the trigger.
Security
- Domain whitelist — config is only honored on listed domains.
- Public config endpoint — returns non-secret display settings only.
- Authenticated admin APIs — create/update/delete require JWT.
Troubleshooting
| Issue | Check |
|---|---|
| No trigger | Domain not whitelisted or URL does not match page rules |
| 403 on config | Instance inactive or domain mismatch |
| Sidebar blank | User must sign in inside sidebar; check API CORS in console |
| Cached old config | Config responses are short-lived; hard-refresh |
Next
- Embed API reference
- Logo cloud embed — showcase auth communities