CocciFlows Documentation

For the AI Customer Service Agent - Starter (v1.1.7). The same guides ship inside your product download; this page is the online copy.

Using Business? See the Business documentation.

1 · Getting started

After purchase you receive a small zip package. The whole journey:

1. Extract the zip and open START_HERE.md.
2. Double-click the setup launcher for your system, a guided wizard opens in your browser.
3. Follow the wizard: business details → knowledge → OpenAI → n8n → email → install → health check → activate.
4. Test your agent in the built-in chat, then copy the website snippet into your site.

Typical time from download to live: about 15–30 minutes, most of it writing your FAQs.

2 · Requirements

3 · Installation

Windows: double-click Start-Setup-Windows.cmd. If Node.js is missing, the launcher opens the download page, install the LTS version and run it again.

macOS: double-click start-setup-mac.command. On first launch macOS may warn about an unidentified developer: right-click the file → Open → Open. This is a one-time step.

Linux: run ./start-setup-linux.sh in a terminal.

The wizard runs locally at http://127.0.0.1:7378, keep the launcher window open while you use it. Your answers are saved as you go (your keys are deliberately not saved to disk; if you close the wizard you'll re-enter them). Clicking Install personalizes the agent workflow with your configuration and installs it into your n8n through the n8n API, no file editing, no server restarts. Re-running Install later updates your installation; it never creates duplicates.

4 · OpenAI setup

1. Create an account at platform.openai.com and add billing.
2. Recommended: set a monthly spend limit (Settings → Limits). Typical customer-service usage on the default model costs a fraction of a cent per question.
3. Create an API key (API keys → Create new secret key) and paste it into the wizard's AI step. The wizard tests it immediately.

During installation your key is stored encrypted inside your own n8n as a credential, not in any file, and never sent to CocciFlows. The default model is a low-cost one suited to support conversations; you can enter any chat model available on your account.

5 · n8n setup

n8n is the automation engine your agent runs on. You never build the workflow yourself: the setup wizard creates and installs it for you. All you need is an n8n instance, its address, and an API key.

CocciFlows does not host, resell, or supply n8n or a server, you choose and own your instance. If you self-host with Docker, always create a data volume (-v n8n_data:/home/node/.n8n): without it every restart erases your n8n account, credentials, and installed agent.

Then create an API key: n8n → Settings → n8n API → Create an API key (labelled just API in older versions), and enter your n8n address + key in the wizard's Connect step. The wizard verifies reachability, authentication, and version, version detection is best-effort, so if your n8n does not publish its version the wizard says so honestly instead of assuming. The API key is used by the wizard only (install, health checks, activation, update, uninstall), the running agent never uses it.

6 · Email setup

Escalation emails are sent through your own email provider via SMTP. In the wizard's Email step, either:

• Enter SMTP details (host, port, username, password), the wizard creates the credential inside your n8n for you. Gmail/Google Workspace users: create an App Password (myaccount.google.com → Security → App passwords); your normal password will not work. Or:
• Configure manually: after Install, open the workflow in n8n, click the Notify Business node, choose your SMTP credential (or create one), save, then press "I configured SMTP manually" in the wizard so health checks know.

Escalation emails contain: the reason, the conversation ID, the customer's question, and any contact details the customer chose to share. Nothing else is stored anywhere.

7 · Website widget

The wizard's Website chat step generates your snippet. Self-hosted option: upload widget/cocciflows.js from your package to your website, then paste the snippet before </body>:

<script src="/cocciflows.js"
  data-endpoint="https://YOUR-N8N/webhook/cocciflows-chat-…"
  data-agent-name="Assistant"
  data-welcome="Hi! Ask me anything about our business."
  data-position="right"></script>

Options: data-position (right/left), data-accent (any hex color), data-agent-name, data-welcome. A CocciFlows-hosted copy of the widget (same snippet, no upload) will be announced with a product update. Preview locally any time with the included widget/demo.html.

8 · Testing your agent

1. Wizard test chat (last step), talks to your real installed agent. Try a question from your FAQs, a question you did not configure, and "I want to speak to a human".
2. Health check (step 9), re-run any time; after activation it also tests the live webhook end-to-end.
3. Command line:

   curl -X POST "https://YOUR-N8N/webhook/cocciflows-chat-…" \
     -H "Content-Type: application/json" \
     -d '{"message": "What are your opening hours?"}'

   A JSON reply with "status": "answered" means you're live.

9 · Troubleshooting

The full troubleshooting guide, including log reading, ships in your package (docs/TROUBLESHOOTING.md).

10 · Security & data flow

• Conversations flow: your website → your n8n → your OpenAI account. CocciFlows operates no server in this path and cannot see your data.
• Your OpenAI key lives encrypted in your n8n's credential store; your n8n API key is used only by the local wizard; SMTP credentials live in n8n like any other n8n credential.
• The setup wizard binds to your computer only (127.0.0.1), keeps secrets in memory, and never writes them to disk.
• Your agent's webhook gets a random, hard-to-guess address. Incoming messages are validated and size-limited; common prompt-manipulation attempts ("ignore your instructions", "reveal your configuration") are deflected before reaching the AI. These defenses are meaningful but not absolute, no AI safety measure is.
• The widget renders all text as plain text (never HTML) and contains no secrets, it is a public file you can read.
• Logs record events (answered, escalated, failed), never message content, keys, or addresses.
• Data minimization: customers are never required to hand over personal details to ask a question; contact details are optional and used only for your team's follow-up email.

CocciFlows does not claim regulatory certifications (HIPAA, SOC 2, …). Your OpenAI usage is governed by your agreement with OpenAI.

11 · Uninstall

1. Open the setup wizard and use Uninstall: it deactivates and deletes the agent workflow and removes the CocciFlows credentials from your n8n. (Manual alternative: delete them in n8n directly.)
2. Remove the widget snippet (and cocciflows.js, if self-hosted) from your website.
3. Optionally revoke the n8n API key and OpenAI key you used.

Nothing else is installed anywhere.

12 · FAQ