Embed the Dashboard

Embedding the dashboard is available to enterprise customers with reseller API access. Contact us to get started.

The Answering Agent dashboard can be embedded into your website, providing a seamless customer support platform for your users. The embed system uses secure, compact tokens that authenticate users without exposing sensitive credentials.

Overview

The embed system works in three steps:

Create a user

Use the Users API to create a user - this returns an embed_token

Manage embed tokens

Use the dedicated endpoints to get current token or generate new ones

Embed the dashboard

Use the token in your frontend to embed the dashboard

Getting Embed Tokens

From User Creation

When you create a user, the response includes an embed_token:

{
  "embed_token": "MTIzNDV8ZDgyZDk3Mzg1OTAxNTkzNA",
  "user": { /* user details */ },
  "team": { /* team details */ },
  "locations": [ /* locations */ ]
}

Managing Existing Tokens

For existing users, you can retrieve or regenerate embed tokens using dedicated endpoints:

Get Current Embed Token

GET /v1/users/{external_id}/embed-token

Example:

curl -H "X-API-KEY: your-api-key" \
     https://answeringagent.com/api/v1/users/your-user-123/embed-token

Response:

{
  "embed_token": "MTIzNDV8ZDgyZDk3Mzg1OTAxNTkzNA",
  "user_id": "your-user-123"
}

Generate New Embed Token

POST /v1/users/{external_id}/embed-token

Generating a new embed token invalidates the previous token by rotating the user’s signing secret. Any embedded dashboards using the old token will need to be updated.

Example:

curl -X POST \
     -H "X-API-KEY: your-api-key" \
     https://answeringagent.com/api/v1/users/your-user-123/embed-token

Response:

{
  "embed_token": "OTg3NjV8YWJjZGVmZ2hpams1Njc4OTA",
  "user_id": "your-user-123",
  "message": "New embed token generated successfully"
}

Embedding the Dashboard

There are two ways to embed the Answering Agent dashboard:

Iframe Embed (Recommended) - Simple, isolated, no JavaScript needed
Script Embed - More control, direct DOM integration

Iframe Embed (Recommended)

The easiest way to embed the dashboard with complete DOM isolation:

<iframe
  src="https://answeringagent.com/dashboard.html?token=MTIzNDV8ZDgyZDk3Mzg1OTAxNTkzNA"
  width="100%"
  height="600px"
  frameborder="0"
  style="border: none;">
</iframe>

Benefits:

✅ Zero JavaScript required - just paste the iframe
✅ Complete DOM isolation from your page
✅ Works with strict Content Security Policies
✅ No conflicts with your site’s CSS or JavaScript
✅ Easy to implement in any CMS or page builder

Custom API URL (Playground Mode):

<iframe
  src="https://answeringagent.com/dashboard.html?token=YOUR_TOKEN&api-url=https://playground.answeringagent.com/api"
  width="100%"
  height="600px"
  frameborder="0">
</iframe>

Script Embed

For more direct integration into your page’s DOM:

<!-- Container for the embedded dashboard -->
<div
  id="answering-agent"
  data-token="MTIzNDV8ZDgyZDk3Mzg1OTAxNTkzNA">
</div>

<!-- Load the embed script -->
<script type="module" src="https://answeringagent.com/embed.js"></script>

Playground Mode: For testing and development with the script embed:

<!-- Container for playground embed -->
<div
  id="answering-agent"
  data-token="MTIzNDV8ZDgyZDk3Mzg1OTAxNTkzNA"
  data-api-url="https://playground.answeringagent.com/api">
</div>

<!-- Load the embed script -->
<script type="module" src="https://answeringagent.com/embed.js"></script>

Quick Start Checklist

For Iframe Embed:

✅ Iframe tag with src pointing to /dashboard.html?token=YOUR_TOKEN
✅ Valid embed token in the URL query parameter

For Script Embed:

✅ Container div with id="answering-agent"
✅ Embed token in data-token attribute
✅ Embed script loaded from https://answeringagent.com/embed.js
✅ API URL in data-api-url attribute (optional, for playground/custom environments)

That’s it! The embed automatically detects embedded mode from the presence of data-token and handles all other configuration.

Dynamic Token Management

For production applications, you should dynamically fetch and inject tokens:

async function loadAnsweringAgentDashboard(userId) {
  try {
    // Fetch the embed token from your backend (recommended)
    const response = await fetch(`/api/users/${userId}/embed-token`, {
      headers: {
        'Authorization': `Bearer ${userAuthToken}`
      }
    });

    const data = await response.json();

    // Set the embed token on the container
    const embedContainer = document.getElementById('answering-agent');
    embedContainer.setAttribute('data-token', data.embed_token);

    // Load the embed script if not already loaded
    if (!document.querySelector('script[src*="embed.js"]')) {
      const script = document.createElement('script');
      script.type = 'module';
      script.src = 'https://answeringagent.com/embed.js';
      document.head.appendChild(script);
    }
  } catch (error) {
    console.error('Failed to load Answering Agent dashboard:', error);
  }
}

React Component Example

function AnsweringAgentDashboard({ userId }) {
  const [embedToken, setEmbedToken] = useState(null);

  useEffect(() => {
    // Fetch embed token
    fetch(`/api/users/${userId}/embed-token`)
      .then(res => res.json())
      .then(data => setEmbedToken(data.embed_token));
  }, [userId]);

  useEffect(() => {
    if (embedToken) {
      // Load embed script
      const script = document.createElement('script');
      script.type = 'module';
      script.src = 'https://answeringagent.com/embed.js';
      document.head.appendChild(script);

      return () => document.head.removeChild(script);
    }
  }, [embedToken]);

  return (
    <div
      id="answering-agent"
      data-token={embedToken}
      style={{ width: '100%', height: '600px' }}
    />
  );
}

Security Features

Compact Tokens

URL-safe base64 encoding without padding
Optimized for query parameters and data attributes

Secure Validation

Uses HMAC-SHA256 for cryptographic integrity
Tokens are tied to specific users and cannot be transferred
Automatic signing secret rotation invalidates old tokens

Token Lifecycle

Tokens don’t expire but can be invalidated by generating new ones
Each user can only have one valid token at a time
Signing secrets are unique per user and automatically generated

Error Handling

Invalid or Expired Tokens

If an embed token is invalid, the embedded dashboard will show an authentication error. Common causes:

Token was invalidated by generating a new one
Token is malformed or corrupted
User account was deleted or suspended

Missing Configuration

If the required window settings are not properly configured, you may see:

Console warnings about missing answeringAgentSettings
Dashboard not loading or appearing blank
Authentication errors

Best Practices

Proxy through your backend - Don’t expose your API key in frontend code
Store tokens securely in your database associated with user accounts
Use unique embed IDs - Each embed instance should have a unique id in the settings
Set configuration before script load - Always configure window.isAnsweringAgentEmbedded and window.answeringAgentSettings before loading the embed script
Regenerate tokens when users change passwords or for security rotations
Handle errors gracefully with fallback UI when embedding fails
Use HTTPS for all communication with embed tokens
Monitor usage and regenerate tokens if you suspect compromise

Troubleshooting

Dashboard Won’t Load

Verify the embed token is valid using the validation endpoint
Confirm the container has id="answering-agent" (exact match required)
Check browser console for JavaScript errors
Ensure the embed container has proper dimensions and is visible

Authentication Errors

The token may have been invalidated - generate a new one
Check that the token matches the user making the request
Verify your API key has proper permissions for the user
Ensure the data-token attribute is set on the container

Configuration Errors

Verify the container has exactly id="answering-agent"
Check that the data-token attribute contains a valid embed token
Ensure the embed script loads successfully from https://answeringagent.com/embed.js
Monitor network requests to verify API calls are reaching the correct endpoint

Performance Issues

Cache embed tokens in your backend to avoid repeated API calls
Consider preloading the embed script on pages where it will be used
Monitor embed container sizing to prevent layout shifts

Getting Started

Guides

API Reference

API Playground

Overview

Getting Embed Tokens

From User Creation

Managing Existing Tokens

Get Current Embed Token

Generate New Embed Token

Embedding the Dashboard

Iframe Embed (Recommended)

Script Embed

Quick Start Checklist

Dynamic Token Management

React Component Example

Security Features

Compact Tokens

Secure Validation

Token Lifecycle

Error Handling

Invalid or Expired Tokens

Missing Configuration

Best Practices

Troubleshooting

Dashboard Won’t Load

Authentication Errors

Configuration Errors

Performance Issues

Getting Started

Guides

API Reference

API Playground

​Overview

​Getting Embed Tokens

​From User Creation

​Managing Existing Tokens

​Get Current Embed Token

​Generate New Embed Token

​Embedding the Dashboard

​Iframe Embed (Recommended)

​Script Embed

​Quick Start Checklist

​Dynamic Token Management

​React Component Example

​Security Features

​Compact Tokens

​Secure Validation

​Token Lifecycle

​Error Handling

​Invalid or Expired Tokens

​Missing Configuration

​Best Practices

​Troubleshooting

​Dashboard Won’t Load

​Authentication Errors

​Configuration Errors

​Performance Issues

Overview

Getting Embed Tokens

From User Creation

Managing Existing Tokens

Get Current Embed Token

Generate New Embed Token

Embedding the Dashboard

Iframe Embed (Recommended)

Script Embed

Quick Start Checklist

Dynamic Token Management

React Component Example

Security Features

Compact Tokens

Secure Validation

Token Lifecycle

Error Handling

Invalid or Expired Tokens

Missing Configuration

Best Practices

Troubleshooting

Dashboard Won’t Load

Authentication Errors

Configuration Errors

Performance Issues