Hugging Face's logo

Spaces:
cuivienen
/
synderesis-api
Running

App Files Community
synderesis-api / customer-agent /docs /customer-setup-guide.md
cuivienen's picture
cuivienen
Deploy Synderesis API Docker Space
10ff0f9 verified
preview code
|
Raw
History Blame Contribute Delete
7.37 kB

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
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/
  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/

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>:

<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

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