@primexperts/pulse-agent

Embeddable floating Pulse chat widget for client websites.

Documentation

• Integration channels guide: docs/INTEGRATION-CHANNELS.md
• Full implementation guide: docs/IMPLEMENTATION-GUIDE.md
• FAQ: docs/FAQ.md
• Troubleshooting: docs/TROUBLESHOOTING.md
• Changelog: docs/CHANGELOG.md

Install

npm install @primexperts/pulse-agent

Usage

import { createPulseAgent } from '@primexperts/pulse-agent';

const agent = createPulseAgent({
  slug: 'client-abc',
  apiBaseUrl: 'https://pulse.service.primexperts.co.za',
  requireProfile: true,
  autoOpen: false
});

// optional
agent.open();

Browser/CDN Usage (No Bundler)

<script src="https://unpkg.com/@primexperts/pulse-agent/dist/browser/pulse-agent.global.js"></script>
<script>
  const agent = window.PulseAgent.createPulseAgent({
    slug: 'client-abc',
    apiBaseUrl: 'https://pulse.service.primexperts.co.za'
  });
</script>

Required Backend Endpoints

• GET /api/pulse/public/webchat/resolve?slug=<slug>
• POST /api/pulse/public/webchat/{widgetToken}/message
• GET /api/pulse/public/webchat/{widgetToken}/stream?conversationId=<id>

API

createPulseAgent(options)

Options:

• slug (required): public organization slug.
• apiBaseUrl (optional): defaults to https://pulse.service.primexperts.co.za.
• followUpEmailTo (optional): preferred destination for transcript follow-up emails.
• mount (optional): container element or selector, defaults to document.body.
• autoOpen (optional): open panel immediately.
• requireProfile (optional): requires name/email before first message, default true.
• widgetToken (optional): bypass slug resolution.
• title (optional): panel title.

Returns PulseAgentHandle:

• open()
• close()
• destroy()
• update(partialOptions)

Notes

• This package is framework-agnostic and browser-only.
• No dashboard/auth code is included in this project.
• If widget keys cannot be resolved, the chat shows an error message and retries resolution on the next send attempt.
• npm run build now outputs:
  • ESM + type declarations in dist/
  • browser global bundle in dist/browser/pulse-agent.global.js

Versioning

Use the built-in version script instead of editing files manually:

npm run version:patch
# or
npm run version:minor
npm run version:major
# or custom semver
npm run version:bump -- 1.2.3

This updates both package.json and package-lock.json.