Embed the Dashboard

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

Summary/Quick Start

Get your API key from Settings → API Keys in your Answering Agent dashboard
Create a user via POST /api/v1/users with X-API-KEY header → receives embed_token in response
Store the embed token in your database alongside the user
Embed the dashboard using <iframe src="https://answeringagent.com/dashboard.html?token=EMBED_TOKEN">
User’s browser loads embed → token is auto-exchanged for session auth

X-API-KEY = your server only. embed_token = safe for browsers.

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.

Authentication Overview

The embed system involves two different authentication contexts:

Your Server (Partner)

Uses the X-API-KEY header to call the Partner API and retrieve embed tokens for your users.

User's Browser (End User)

Uses the embed_token which is automatically exchanged for session authentication.

Never expose your X-API-KEY in client-side code. The API key is for server-to-server communication only. End users only need the embed_token.

How Tokens Flow

Your server requests an embed token

Call the Partner API with your X-API-KEY to get an embed_token for a specific user.

Your server passes the token to the browser

Inject the embed_token into your HTML page (via data-token attribute or iFrame URL).

The browser exchanges the token

When the embed loads, it automatically calls /api/validate-embed-token to exchange the embed_token for a session auth_token.

User is authenticated

The browser stores the auth_token and uses it for all subsequent API calls. This happens automatically.

Getting Embed Tokens (Server-Side)

These endpoints require your X-API-KEY header and should only be called from your server, never from client-side code.

From User Creation

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

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

Managing Existing Tokens

For existing users, your server can retrieve or regenerate embed tokens:

Get Current Embed Token

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

cURL
Node.js
PHP

# Called from YOUR SERVER, not the browser
curl -H "X-API-KEY: your-api-key" \
     https://answeringagent.com/api/v1/users/your-user-123/embed-token

// Server-side code (Express, Next.js API route, etc.)
const response = await fetch(
  'https://answeringagent.com/api/v1/users/your-user-123/embed-token',
  {
    headers: {
      'X-API-KEY': process.env.ANSWERING_AGENT_API_KEY // Never expose this!
    }
  }
);
const { embed_token } = await response.json();
// Pass embed_token to your frontend template

// Server-side code (Laravel, etc.)
$response = Http::withHeaders([
    'X-API-KEY' => config('services.answering_agent.api_key'),
])->get('https://answeringagent.com/api/v1/users/your-user-123/embed-token');

$embedToken = $response->json('embed_token');
// Pass $embedToken to your view

Response:

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

Generate New Embed Token

POST /api/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.

# Called from YOUR SERVER
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 script automatically exchanges the embed_token for session authentication.

Dynamic Token Integration

For production applications, your server should fetch embed tokens and pass them to the frontend.

Server-Side Endpoint

Create an endpoint in your backend that fetches the embed token:

Node.js / Express
PHP / Laravel

// routes/embed.js - YOUR SERVER
app.get('/api/embed-token', async (req, res) => {
  // 1. Authenticate your own user (your auth system)
  const user = await authenticateRequest(req);
  if (!user) return res.status(401).json({ error: 'Unauthorized' });

  // 2. Get the user's external ID (their ID in Answering Agent)
  const externalId = user.answeringAgentId;

  // 3. Fetch embed token from Answering Agent using YOUR API key
  const response = await fetch(
    `https://answeringagent.com/api/v1/users/${externalId}/embed-token`,
    {
      headers: {
        'X-API-KEY': process.env.ANSWERING_AGENT_API_KEY
      }
    }
  );

  const { embed_token } = await response.json();
  res.json({ embed_token });
});

// routes/api.php - YOUR SERVER
Route::get('/embed-token', function (Request $request) {
    // 1. Authenticate your own user (your auth system)
    $user = $request->user();

    // 2. Get the user's external ID (their ID in Answering Agent)
    $externalId = $user->answering_agent_id;

    // 3. Fetch embed token from Answering Agent using YOUR API key
    $response = Http::withHeaders([
        'X-API-KEY' => config('services.answering_agent.api_key'),
    ])->get("https://answeringagent.com/api/v1/users/{$externalId}/embed-token");

    return response()->json([
        'embed_token' => $response->json('embed_token'),
    ]);
})->middleware('auth');

Client-Side Integration

Your frontend calls your backend (not Answering Agent directly):

async function loadAnsweringAgentDashboard() {
  try {
    // Call YOUR backend endpoint (which uses X-API-KEY internally)
    const response = await fetch('/api/embed-token', {
      headers: {
        'Authorization': `Bearer ${yourSessionToken}` // Your auth
      }
    });

    const { embed_token } = await response.json();

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

    // Load the embed script - it handles token exchange automatically
    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 dashboard:', error);
  }
}

The embed script automatically handles exchanging the embed_token for a session token. You don’t need to call /api/validate-embed-token yourself.

React Component Example

function AnsweringAgentDashboard() {
  const [embedToken, setEmbedToken] = useState(null);
  const [error, setError] = useState(null);

  useEffect(() => {
    // Call YOUR backend (which calls Partner API with X-API-KEY)
    fetch('/api/embed-token')
      .then(res => res.json())
      .then(data => setEmbedToken(data.embed_token))
      .catch(err => setError(err.message));
  }, []);

  useEffect(() => {
    if (embedToken) {
      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]);

  if (error) return <div>Failed to load dashboard</div>;
  if (!embedToken) return <div>Loading...</div>;

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

Your /api/embed-token endpoint should authenticate the request using your own auth system, then call the Answering Agent Partner API with your X-API-KEY.

Security Features

Token Types

Token	Who Uses It	How It’s Sent	How to Get It
X-API-KEY	Your server	`X-API-KEY` header	Dashboard → Settings → API Keys
embed_token	User’s browser	`data-token` attr or URL param	Partner API response
auth_token	User’s browser	`Authorization: Bearer` header	Auto-exchanged from embed_token

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 embed 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 embed container is not properly configured, you may see:

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

Best Practices

Server-Side (Your Backend)

Never expose X-API-KEY - Keep your API key in environment variables on your server
Proxy embed tokens - Your backend should fetch tokens and pass them to the frontend
Cache tokens - Store embed tokens in your database to reduce API calls
Regenerate on security events - Rotate tokens when users change passwords

Client-Side (User’s Browser)

Use the embed script - Let embed.js handle token exchange automatically
Set data-token before loading script - Ensure the container has the token attribute set
Handle errors gracefully - Show fallback UI if embedding fails
Use HTTPS only - Never transmit tokens over insecure connections

Troubleshooting

Dashboard Won’t Load

Verify the embed token is valid by checking the Partner API response
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 embed token may have been invalidated - fetch a new one from the Partner API
Check that your server is using the correct X-API-KEY
Verify the user exists in Answering Agent
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 Partner 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

POS Integrations

API Reference

API Playground

Summary/Quick Start

Authentication Overview

Your Server (Partner)

User's Browser (End User)

How Tokens Flow

Getting Embed Tokens (Server-Side)

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 Integration

Server-Side Endpoint

Client-Side Integration

React Component Example

Security Features

Token Types

Compact Tokens

Secure Validation

Token Lifecycle

Error Handling

Invalid or Expired Tokens

Missing Configuration

Best Practices

Server-Side (Your Backend)

Client-Side (User’s Browser)

Troubleshooting

Dashboard Won’t Load

Authentication Errors

Configuration Errors

Performance Issues

Getting Started

Guides

POS Integrations

API Reference

API Playground

​Summary/Quick Start

​Authentication Overview

Your Server (Partner)

User's Browser (End User)

​How Tokens Flow

​Getting Embed Tokens (Server-Side)

​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 Integration

​Server-Side Endpoint

​Client-Side Integration

​React Component Example

​Security Features

​Token Types

​Compact Tokens

​Secure Validation

​Token Lifecycle

​Error Handling

​Invalid or Expired Tokens

​Missing Configuration

​Best Practices

​Server-Side (Your Backend)

​Client-Side (User’s Browser)

​Troubleshooting

​Dashboard Won’t Load

​Authentication Errors

​Configuration Errors

​Performance Issues

Summary/Quick Start

Authentication Overview

How Tokens Flow

Getting Embed Tokens (Server-Side)

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 Integration

Server-Side Endpoint

Client-Side Integration

React Component Example

Security Features

Token Types

Compact Tokens

Secure Validation

Token Lifecycle

Error Handling

Invalid or Expired Tokens

Missing Configuration

Best Practices

Server-Side (Your Backend)

Client-Side (User’s Browser)

Troubleshooting

Dashboard Won’t Load

Authentication Errors

Configuration Errors

Performance Issues