Spaces:
Running
Running
| # Customer setup guide — Synderesis Customer Service Agent | |
| **Who this is for:** the person who runs your website (shop owner, parish webmaster, charity communications). | |
| **You do not need a developer API key** on your website. | |
| Time needed: about **15–20 minutes** the first time. | |
| --- | |
| ## 1. What you get | |
| A chat bubble on your website that: | |
| 1. Answers routine questions from **your** FAQ (hours, shipping, products, returns…) | |
| 2. Speaks in a tone you choose | |
| 3. Offers **leave a message for a person** when the question is sensitive or unknown | |
| 4. Can notify you by **email** and/or a **webhook** (Zapier, Make, helpdesk) | |
| A small “Powered by Synderesis” credit always appears on the widget. | |
| --- | |
| ## 2. What you need before starting | |
| | Need | Notes | | |
| |------|--------| | |
| | Synderesis account | [synderesis.eu/account](https://www.synderesis.eu/account/) | | |
| | Early access for live chat | While waitlist-only, live answers need early access (`chat_access`). You can still create agents and install the snippet. | | |
| | Website access | WordPress admin **or** ability to paste one script before `</body>` | | |
| | Escalation contact | An email address **or** HTTPS webhook URL (or both) | | |
| **Keys explained** | |
| | Key | Looks like | On website? | | |
| |-----|------------|-------------| | |
| | Public **site key** | `pk_live_…` | **Yes** — used by the chat bubble | | |
| | Secret **API key** | `syn_…` | **Never** | | |
| --- | |
| ## 3. Fifteen-minute checklist | |
| - [ ] Sign in to Synderesis | |
| - [ ] Open agent admin | |
| - [ ] Create agent (name, voice, handoff) | |
| - [ ] Copy `pk_live_…` site key | |
| - [ ] Upload FAQ (paste or file) | |
| - [ ] Test on the private test page | |
| - [ ] Install on WordPress **or** paste snippet | |
| - [ ] Lock allowed websites (remove `*` when live) | |
| - [ ] Confirm a test “leave a message” reaches email/webhook | |
| --- | |
| ## 4. Step 1 — Sign in | |
| 1. Open [https://www.synderesis.eu/account/](https://www.synderesis.eu/account/) | |
| 2. Sign in or create an account | |
| 3. If you were invited for early access, redeem your invitation code when prompted | |
| --- | |
| ## 5. Step 2 — Open agent admin | |
| Open: **[https://www.synderesis.eu/customer-agent/admin/](https://www.synderesis.eu/customer-agent/admin/)** | |
| If you are not signed in, you will be asked to sign in first. | |
| **What the fields mean** | |
| | Field | Meaning | | |
| |-------|---------| | |
| | Business / shop name | Shown in the chat header | | |
| | Welcome message | First message visitors see | | |
| | How should it sound? | Tone (warm, short, formal…) | | |
| | Escalation email | Where human handoffs are emailed | | |
| | Webhook URL (optional) | `https://…` endpoint for JSON handoffs | | |
| | Allowed websites | Origins that may use the agent, e.g. `https://www.yoursite.com`. Use `*` only while testing | | |
| --- | |
| ## 6. Step 3 — Create agent and save the site key | |
| 1. Fill the form and click **Create agent** | |
| 2. **Immediately copy** the public site key (`pk_live_…`) — it is shown once | |
| 3. Copy the **install snippet** as well | |
| If you lose the key: click **Rotate site key**, copy the new key, and update your website/plugin. | |
| --- | |
| ## 7. Step 4 — Add knowledge (FAQ) | |
| The agent should **only** answer from what you provide. | |
| **Good FAQ topics** | |
| - Opening hours | |
| - Shipping / delivery | |
| - Returns | |
| - Products / services | |
| - How to contact a person | |
| **Do not paste** confidential pastoral cases, passwords, or unpublished legal strategy. | |
| You can: | |
| - Paste text in admin, or | |
| - Upload a `.txt` / `.md` / `.pdf` file (text extract), or | |
| - Import a **public HTTPS page** URL (e.g. your shipping policy page) | |
| After real chats, open **Coverage** in admin to see questions that missed your FAQ. | |
| Start from `templates/sample-faq.txt` if helpful. | |
| --- | |
| ## 8. Step 5 — Test privately | |
| Open: | |
| `https://www.synderesis.eu/customer-agent/test/?key=pk_live_YOUR_KEY` | |
| This page is **not** linked from the public marketing site. | |
| Try: | |
| 1. A question that is in your FAQ | |
| 2. A question that is **not** in your FAQ (should admit unknown / offer handoff) | |
| 3. **Leave a message** — confirm email and/or webhook | |
| If chat says service is not enabled: early access is required for live model answers. Setup and install still work. | |
| --- | |
| ## 9. Step 6 — Install on your website | |
| ### A) WordPress (easiest) | |
| 1. Install the plugin zip | |
| `synderesis-customer-agent-1.4.0.zip` | |
| (from Synderesis, or built with `integrations/wordpress/scripts/build-zip.ps1`) | |
| 2. WordPress → **Plugins → Add New → Upload Plugin → Activate** | |
| 3. **Settings → Synderesis Agent** | |
| 4. Paste `pk_live_…` (never `syn_…`) | |
| 5. API base: usually `https://www.synderesis.eu` | |
| 6. **Save settings** | |
| 7. Click **Test connection** | |
| 8. In Synderesis admin, allow this site’s origin (the WP page shows your origin) | |
| 9. Hard-refresh / purge cache on the public site | |
| ### B) Any other site (custom HTML, Shopify theme, Squarespace, Wix) | |
| Paste before `</body>`: | |
| ```html | |
| <script | |
| src="https://www.synderesis.eu/embed/agent.js" | |
| data-site-key="pk_live_YOUR_KEY_HERE" | |
| data-api-base="https://www.synderesis.eu" | |
| async></script> | |
| ``` | |
| More variants: [install-snippets.md](./install-snippets.md) | |
| --- | |
| ## 10. Step 7 — Lock for production | |
| 1. In admin, set **Allowed websites** to your real origin(s), e.g. `https://www.yoursite.com` | |
| 2. Remove `*` when you are finished testing | |
| 3. Confirm the chat bubble on a real phone | |
| 4. Confirm handoff still works | |
| --- | |
| ## 11. Day-2 operations | |
| | Task | Where | | |
| |------|--------| | |
| | Update FAQ | Admin → select agent → Knowledge | | |
| | Read visitor messages | Admin → Escalations | | |
| | Change handoff email/webhook | Admin → update agent (save) | | |
| | Rotate compromised site key | Admin → Rotate site key → update WP/snippet | | |
| | Export data | `GET /v1/agents/{id}/export` (signed-in) or ask support | | |
| Escalations are retained for a limited period (default **90 days**), then purged. | |
| --- | |
| ## 12. Privacy blurb (adapt for your policy) | |
| > Our website may offer an automated support assistant provided by Synderesis. Messages you send are processed to answer routine questions and may be stored briefly so our team can follow up when you ask for a person. Do not submit sensitive personal data you would not send by email. See Synderesis’s privacy materials and contact us for data requests. | |
| --- | |
| ## 13. Troubleshooting | |
| | Symptom | Try this | | |
| |---------|----------| | |
| | No chat bubble | Hard refresh; confirm plugin enabled or snippet present; check browser console | | |
| | “Origin not allowed” | Add your exact site origin in admin (include `https://`) | | |
| | Invented answers | Expand FAQ; ask questions only covered by your docs | | |
| | Empty / “don’t know” always | Upload knowledge; check retrieval by testing FAQ wording | | |
| | Cannot open admin | Sign in at `/account/` first | | |
| | Live chat 403 / not enabled | Need early access while waitlist-only | | |
| | Escalation email missing | Check spam; confirm SMTP configured by Synderesis; check webhook instead | | |
| | Plugin rejects key | You pasted `syn_…` — use `pk_live_…` | | |
| --- | |
| ## 14. Limits (honest) | |
| - No live order tracking or payments in the chat (v1) | |
| - Not a substitute for a human on pastoral or legal issues | |
| - Answers are only as good as your FAQ | |
| --- | |
| ## 15. Get help | |
| Email support with: | |
| - Your website URL | |
| - Site key **prefix** only (first characters), never the full secret if avoidable | |
| - Screenshot of the issue | |
| - Approx. time of the problem | |
| --- | |
| *Product package: `customer-agent/` · Version: see `VERSION`* | |