Embedded Chat

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

Integration Steps

Step 1: Get Your API Key

1. Contact [email protected] 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": "[email protected]",
        "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

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

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

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

Getting Started

1. Contact Sales: [email protected]
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

Related Resources

• Security & Compliance - Our security certifications
• Admin Guide - Managing workspaces and users
• BYOK - Use your own AI API keys