PromptlyAgent Support Widget

⚠️ EXAMPLE CODE - NO OFFICIAL SUPPORT

This is a demonstration/example implementation provided as-is for educational purposes and inspiration. It is not an officially supported product and should be considered experimental. Use at your own risk.

• ❌ No official support or maintenance guarantees
• ❌ Not recommended for production use without thorough security review
• ✅ Useful as a reference implementation
• ✅ Community contributions welcome

Embeddable support widget that integrates with PromptlyAgent's chat API. Provides AI-powered, context-aware assistance with element selection and screenshot capture.

⚠️ CRITICAL SECURITY WARNING

This demo implementation exposes API credentials in client-side JavaScript.

DO NOT USE IN PRODUCTION WITHOUT IMPLEMENTING PROPER SECURITY

This example uses Option 4: Direct API with Exposed Token which is:

• ✅ ACCEPTABLE for demos, local development, and testing
• ❌ NOT ACCEPTABLE for production websites
• ❌ INSECURE - API tokens are visible in browser source

Production Security Options

For production deployment, you MUST implement one of these secure approaches:

Option 1: Widget Account System (Recommended - Coming in Phase 2)

• Widget ID instead of API token
• Domain allowlist validation
• Rate limiting per widget
• Similar to Intercom/Zendesk pattern
• Status: Planned for Phase 2

Option 2: Backend Proxy (Enterprise/Self-Hosted)

• Widget calls your backend endpoint
• Backend proxies to PromptlyAgent with stored credentials
• Full control over security and validation
• Status: Example implementations coming in Phase 3

See "Security Considerations" section below for detailed analysis of all security options.

---

Screenshots

Element Selection for Contextual Help

Bug Reporting with Visual Context

---

Features

• 💬 AI-Powered Chat - Real-time streaming responses with PromptlyAgent
• 🎯 Element Selection - Click-to-select DOM elements for contextual help
• 📸 Screenshot Capture - Automatic visual context capture
• 🔄 Session Persistence - Cookie-based session management across page loads
• ⚡ Real-time Streaming - Server-Sent Events (SSE) for instant responses
• 📱 Mobile Responsive - Works on desktop, tablet, and mobile
• 🎨 Customizable - Theme colors, position, and behavior
• 🔧 Standalone - Single JavaScript file, no build process required

---

Quick Start

1. Prerequisites

You need:

• A running PromptlyAgent instance
• API Bearer token (generated in Filament admin)
• Promptly Manual agent ID
• CORS configured to allow your domain

2. Load Dependencies

Add html2canvas library (required for screenshot capture):

<!-- Load html2canvas for screenshot capture -->
<script src="https://cdn.jsdelivr.net/npm/html2canvas@1.4.1/dist/html2canvas.min.js"></script>

3. Load Widget

<!-- Load PromptlySupport widget -->
<script src="promptly-support.js"></script>

4. Configure & Initialize

<script>
    PromptlySupport.init({
        // Required: Your PromptlyAgent instance URL
        apiBaseUrl: 'https://your-instance.com',

        // Required: Bearer token (⚠️ EXPOSED - DEMO ONLY)
        apiToken: 'your-api-token-here',

        // Required: Promptly Manual agent ID
        agentId: 123,

        // Optional: Customization
        position: 'bottom-right',
        primaryColor: '#3b82f6',
        enableScreenshots: true,
        debug: false
    });
</script>

5. Test It

Open your page, click the support button (bottom-right corner), and start chatting!

---

Configuration Options

Option	Type	Default	Required	Description
apiBaseUrl	string	-	✅ Yes	PromptlyAgent instance URL (e.g., 'https://promptly.example.com')
apiToken	string	-	✅ Yes	Bearer token for authentication (⚠️ exposed in client code)
agentId	number	-	✅ Yes	Agent ID (Promptly Manual agent)
position	string	'bottom-right'	No	Widget position: 'bottom-right', 'bottom-left', 'top-right', 'top-left'
primaryColor	string	'#3b82f6'	No	Theme color (CSS color value)
sessionCookieName	string	'promptly_session_id'	No	Cookie name for session persistence
sessionCookieExpiry	number	30	No	Cookie expiry in days
fabText	string	'?'	No	Floating action button text
widgetTitle	string	'Help & Support'	No	Chat window header title
placeholderText	string	'Ask a question...'	No	Input field placeholder
welcomeMessage	string	'Hi! How can I help you today?'	No	Initial greeting message
enableScreenshots	boolean	true	No	Enable screenshot capture (requires html2canvas)
debug	boolean	false	No	Enable debug logging to console

Example: Custom Configuration

PromptlySupport.init({
    apiBaseUrl: 'https://promptly.example.com',
    apiToken: 'prod_abc123...',
    agentId: 5,
    position: 'bottom-left',
    primaryColor: '#10b981',
    fabText: '💬',
    widgetTitle: 'Support Chat',
    welcomeMessage: 'Hello! How may I assist you?',
    enableScreenshots: true,
    debug: true
});

---

API Reference

Initialization

PromptlySupport.init(config)

Initialize the widget with configuration object. Must be called before the widget can be used.

Returns: void

Public Methods

PromptlySupport.newSession()

Clear the current session and create a new one. Clears conversation history and selected element.

PromptlySupport.newSession();

Returns: void

PromptlySupport.close()

Programmatically close the chat window.

PromptlySupport.close();

Returns: void

Alternative: Data Attribute Configuration

You can also configure via data-promptly-config attribute:

<script
    src="promptly-support.js"
    data-promptly-config='{"apiBaseUrl":"https://your-instance.com","apiToken":"your-token","agentId":123}'>
</script>

---

Getting API Token

Generate Token in PromptlyAgent

1. Log into your PromptlyAgent Filament admin panel
2. Navigate to Settings → API Tokens
3. Click "Generate New Token"
4. Give it a name (e.g., "Support Widget - Demo")
5. Copy the generated token
6. ⚠️ Important: Store this token securely - it won't be shown again

Using Tinker (Alternative)

./vendor/bin/sail artisan tinker

# Generate token for a user
$user = User::first();
$token = $user->createToken('support-widget')->plainTextToken;
echo $token;

---

Finding Agent ID

Via Tinker (Recommended)

./vendor/bin/sail artisan tinker

# Find Promptly Manual agent ID
$agent = Agent::where('name', 'Promptly Manual')->first();
echo $agent->id;

Via Database Query

./vendor/bin/sail artisan tinker

Agent::where('name', 'LIKE', '%Manual%')->get(['id', 'name']);

Via Filament Admin

1. Navigate to Agents in Filament admin
2. Find "Promptly Manual" agent
3. Click to edit
4. The ID is in the URL: /admin/agents/{id}/edit

---

PromptlyAgent Requirements

Your PromptlyAgent instance must have:

1. Required Endpoints

The widget uses these API endpoints:

• POST /api/v1/chat/sessions - Create new chat session
• GET /api/v1/chat/sessions/{id} - Get session details
• POST /api/v1/chat/stream - Send message with SSE streaming

2. CORS Configuration

Configure CORS in config/cors.php to allow requests from your widget domain:

'paths' => ['api/*'],
'allowed_origins' => ['https://yourdomain.com'],
'allowed_methods' => ['GET', 'POST'],
'allowed_headers' => ['Content-Type', 'Authorization', 'Accept'],
'supports_credentials' => true,

3. Promptly Manual Agent

The widget is designed to work with the "Promptly Manual" agent, which has specialized tools for:

• database_schema_inspector - Database introspection
• safe_database_query - Read-only queries
• secure_file_reader - File reading with security filtering
• directory_listing - File system navigation
• code_search - Code pattern search
• route_inspector - Laravel route mapping

Ensure this agent exists and is active in your PromptlyAgent instance.

---

Browser Support

Supported Browsers

Browser	Version	Support
Chrome	90+	✅ Full
Edge	90+	✅ Full
Firefox	88+	✅ Full
Safari	14+	✅ Full
Mobile Safari	iOS 14+	✅ Full
Mobile Chrome	Android 10+	✅ Full

Required Browser Features

• ES6+ JavaScript (async/await, arrow functions, classes)
• Fetch API
• FormData API
• ReadableStream API (for SSE streaming)
• Promises
• localStorage/Cookies

---

Security Considerations

Current Implementation: Option 4 (Demo/Development Only)

How it works:

• Widget configured with actual API token in JavaScript
• Widget calls PromptlyAgent directly

Pros:

• ✅ Simplest setup for demos
• ✅ No backend needed

Cons:

• ❌ INSECURE - Token exposed in browser
• ❌ Anyone can extract and abuse token
• ❌ Only suitable for examples/demos

Future: Option 1 - Widget Account System (Recommended for Production)

Status: Planned for Phase 2

How it will work:

• Customer creates widget account in PromptlyAgent admin
• Receives unique widget ID (non-sensitive, public identifier)
• Widget configuration: widgetId: 'widget_abc123' (no API token)
• Widget calls PromptlyAgent directly with widget ID
• PromptlyAgent validates widget ID server-side

Security features:

• Domain allowlist (CORS + Referer validation)
• Rate limiting per widget
• Active subscription status checks
• Agent configuration enforcement
• No exposed credentials

Similar to: Intercom, Zendesk, Crisp pattern

Future: Option 2 - Backend Proxy (Enterprise/Self-Hosted)

Status: Example implementations coming in Phase 3

How it works:

• Customer implements backend endpoint: /api/support/chat
• Backend stores PromptlyAgent credentials securely
• Widget calls customer's backend (no credentials)
• Backend proxies to PromptlyAgent with validation

Security features:

• Full control over security logic
• Can add custom business logic
• Rate limiting on customer's terms
• Can log/audit all requests
• Most secure option

Best for: Enterprise deployments, self-hosted solutions

---

Troubleshooting

Widget Not Appearing

Check:

1. JavaScript console for errors
2. Widget script loaded correctly: <script src="promptly-support.js"></script>
3. html2canvas loaded before widget: <script src="https://...html2canvas..."></script>
4. Configuration provided correctly in init() call
5. No JavaScript errors preventing initialization

Debug:

PromptlySupport.init({
    // ... your config
    debug: true  // Enable debug logging
});

CORS Errors

Error: Access to fetch at 'https://...' from origin 'https://...' has been blocked by CORS policy

Solution: Add your domain to config/cors.php in PromptlyAgent:

'allowed_origins' => ['https://yourdomain.com'],

Test CORS:

curl -H "Origin: https://yourdomain.com" \
     -H "Access-Control-Request-Method: POST" \
     -H "Access-Control-Request-Headers: Content-Type,Authorization" \
     -X OPTIONS \
     https://your-promptly-instance.com/api/v1/chat/sessions

Authentication Failed (401)

Error: HTTP 401: Unauthorized

Causes:

1. Invalid or expired API token
2. Token not sent correctly in Authorization header
3. Token doesn't have required permissions

Solution:

• Regenerate API token in Filament admin
• Verify token format: Bearer your-token-here
• Check token has API access permissions

Session Not Persisting

Causes:

1. Cookies blocked by browser settings
2. Cookie SameSite policy issues
3. Third-party cookie restrictions

Solution:

• Check browser cookie settings
• Use same domain for widget and PromptlyAgent (avoids third-party cookies)
• Test in incognito/private mode

Screenshots Not Working

Causes:

1. html2canvas library not loaded
2. enableScreenshots set to false
3. CORS issues with images on page
4. Browser security restrictions

Solution:

• Verify html2canvas loaded: typeof html2canvas !== 'undefined'
• Set enableScreenshots: true in config
• Check console for html2canvas errors
• Test without cross-origin images

Streaming Not Working

Error: Messages appear all at once instead of streaming

Causes:

1. SSE streaming not supported by browser
2. Network proxy buffering responses
3. Server not sending SSE events correctly

Solution:

• Test in supported browser (Chrome, Firefox, Safari)
• Check network tab for text/event-stream content-type
• Verify PromptlyAgent SSE implementation

---

Development

File Structure

examples/support-widget/
├── promptly-support.js          # Main widget implementation (~1300 lines)
├── demo.html                    # Integration example page
├── README.md                    # This documentation
└── configuration.example.js     # Configuration reference

Local Testing

1. Start PromptlyAgent instance:

   cd /path/to/promptlyagent
   ./vendor/bin/sail up -d

2. Generate API token (see "Getting API Token" section)

3. Find Promptly Manual agent ID (see "Finding Agent ID" section)

4. Start local web server:

   cd examples/support-widget
   python3 -m http.server 8000

5. Open demo page:

   http://localhost:8000/demo.html
   

6. Update configuration in demo.html:

   PromptlySupport.init({
       apiBaseUrl: 'http://localhost',  // Your local PromptlyAgent
       apiToken: 'YOUR_GENERATED_TOKEN',
       agentId: YOUR_AGENT_ID,
       debug: true
   });

Debug Mode

Enable debug logging to see widget activity:

PromptlySupport.init({
    // ... your config
    debug: true
});

This will log:

• Widget initialization
• Session creation/restoration
• Element selection events
• Screenshot capture
• API requests and responses
• Streaming events

Browser Console Access

The widget is available globally as PromptlySupport:

// Check widget state
console.log(PromptlySupport.state);

// Get current session
console.log(PromptlySupport.state.chatSession);

// View messages
console.log(PromptlySupport.state.messages);

// Programmatically control widget
PromptlySupport.ui.toggleChat();
PromptlySupport.selector.enable();
PromptlySupport.session.clearSession();

---

Roadmap

✅ Phase 1: Core Functionality (Current)

• Standalone widget implementation
• UI module with FAB and chat window
• Element selector with visual highlighting
• Context capture with screenshots
• Session management with cookies
• API client with SSE streaming
• Demo page with examples
• Documentation with security warnings

🔜 Phase 2: Production Security (Next)

• Widget Account System implementation in PromptlyAgent
• Database table: widget_configurations
• Filament admin resource for widget management
• API endpoint: POST /api/v1/widget/{widgetId}/chat
• Domain allowlist + rate limiting + CORS validation
• Widget updated to use widgetId instead of API token
• Migration guide from Option 4 to Option 1

📚 Phase 3: Backend Proxy Examples

• Node.js/Express proxy example
• PHP/Laravel proxy example
• Python/Flask proxy example
• Ruby/Rails proxy example
• Enterprise deployment guide

🚀 Future Enhancements

• TypeScript rewrite for type safety
• Unit tests with Jest/Vitest
• E2E tests with Playwright/Cypress
• Framework integrations (React/Vue/Angular wrappers)
• Advanced features (file attachments, rich text, voice input)
• Offline support with message queuing
• Multi-language support (i18n)
• Theming system (dark mode, custom themes)
• Analytics and usage tracking

---

License

MIT License

---

Built with ❤️ for PromptlyAgent

Remember: This is a demo implementation. Always implement proper security for production use.