ScoopDocs

Enterprise Features · Legacy self-service product

Embedded Chat

Add Scoop's AI analytics to your own application

You're viewing documentation for the legacy Scoop self-service product. For the current product, see What Is Scoop.

Overview

Embedded Chat lets you add Scoop's AI analytics directly into your own web application. Your users can ask questions about their data using natural language, all within your application's interface.

How It Works

┌─────────────────────────────────────────────────────────────┐
│                    Your Application                          │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. Your backend requests an embed token from Scoop API     │
│                          ↓                                   │
│  2. Token returned (valid for 1 hour)                       │
│                          ↓                                   │
│  3. Your frontend loads Scoop chat in an iframe with token  │
│                          ↓                                   │
│  4. User asks questions, sees charts, gets insights         │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Key Benefits

Benefit Description
No AI Development Use Scoop's mature AI without building your own
Seamless UX Chat appears as part of your application
User Context Each user sees only their permitted data
Your Branding Customize colors and styling
Secure Token-based auth, no passwords exposed

Integration Steps

Step 1: Get Your API Key

  1. Contact sales@scoopanalytics.com to enable embed access
  2. Receive your API key (format: sk_live_...)
  3. Store securely in your backend environment variables

Step 2: Generate Embed Tokens

Your backend requests a token for each user session:

POST https://api.scoopanalytics.com/api/v1/embed/generate-token
Authorization: Bearer sk_live_your_api_key_here
Content-Type: application/json

{
    "workspaceId": "W123",
    "userContext": {
        "id": "your-user-id",
        "email": "user@example.com",
        "name": "Jane Smith"
    }
}

Response:

{
    "embedToken": "eyJhbGciOiJSUzI1NiIs...",
    "expiresAt": "2025-12-03T15:00:00Z"
}

Step 3: Embed the Chat

Add an iframe to your application:

<iframe
    src="https://app.scoopanalytics.com/embedded-chat?token=YOUR_EMBED_TOKEN"
    width="100%"
    height="600"
    frameborder="0"
/>

Token Details

Property Value Notes
Duration 1 hour Regenerate before expiry
Scope Per user Each user gets unique token
Workspace Specified User sees only that workspace
Revocable Yes Can invalidate via API

Security Model

Your API Key

  • Backend only: Never expose in frontend code
  • Rotate regularly: Available in account settings
  • Rate limited: Contact support for higher limits

Embed Tokens

  • Short-lived: Expire after 1 hour
  • User-scoped: Tied to specific user context
  • Workspace-bound: Access only specified workspace
  • Revocable: Can invalidate if needed

Data Isolation

  • Each user only sees their workspace's data
  • No cross-tenant data access
  • User context logged for audit

Customization Options

Styling

Pass URL parameters to customize appearance:

?token=xxx&theme=dark
?token=xxx&primaryColor=%23007bff
Parameter Description Example
theme Light or dark mode dark
primaryColor Accent color (URL encoded) %23007bff
hideHeader Remove Scoop branding true

Events

Listen for events from the embedded chat:

window.addEventListener('message', (event) => {
    if (event.origin !== 'https://app.scoopanalytics.com') return;

    switch (event.data.type) {
        case 'SCOOP_EMBED_READY':
            console.log('Chat loaded');
            break;
        case 'SCOOP_EMBED_TOKEN_EXPIRED':
            // Refresh the token
            refreshEmbedToken();
            break;
        case 'SCOOP_EMBED_ERROR':
            console.error('Chat error:', event.data.error);
            break;
    }
});

Common Use Cases

Customer Portals

Give customers self-service analytics on their data:

  • "Show my usage this month"
  • "Compare my performance to last quarter"
  • "What's trending in my account?"

Internal Tools

Add analytics to operational dashboards:

  • "Show today's orders by region"
  • "Which products are low on inventory?"
  • "Compare sales reps' performance"

Partner Dashboards

Provide partners with insights on shared data:

  • "Show my commission this month"
  • "Which of my referrals converted?"
  • "What's my pipeline value?"

Error Handling

Error Meaning Action
Token expired 1 hour passed Generate new token
Token revoked Manually invalidated Re-authorize user
Invalid token Malformed or tampered Generate new token
Workspace not found Wrong workspace ID Check configuration

Display user-friendly messages:

const errorMessages = {
    'token_expired': 'Your session has expired. Please refresh.',
    'token_revoked': 'Access has been revoked. Contact your administrator.',
    'invalid_token': 'Authentication failed. Please try again.'
};

Requirements

Requirement Details
Plan Enterprise
Setup Contact sales for API key
HTTPS Required for embed
Modern browser Chrome, Firefox, Safari, Edge

Getting Started

  1. Contact Sales: sales@scoopanalytics.com
  2. Receive API Key: For your production environment
  3. Implement Backend: Token generation endpoint
  4. Add iframe: To your application
  5. Test: With your user context

Updated December 3, 2025