Skip to main content

​
Overview

The embedded flow editor uses a 3-step authentication flow that keeps your client secret secure on your backend while giving the iframe short-lived access tokens.

​
Prerequisite: Create an OAuth Client

Before starting the integration, you need to create an OAuth Client linked to the workspace that will be embedded.
  1. Go to the WhataBot Dashboard
  2. Navigate to the Workspaces screen
  3. Click Edit on the desired workspace
  4. Go to the Embed tab
  5. Click Create Client and copy the clientId and clientSecret
Store the clientSecret in a secure location. It is only shown once and should be stored only on your backend.

​
Authentication flow

┌─────────────┐     ┌──────────────┐     ┌──────────────┐
│  Your App    │     │  Your Backend│     │  WhataBot API│
│  (Frontend)  │     │              │     │              │
└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
       │                    │                    │
       │  1. Request OTT    │                    │
       │───────────────────>│                    │
       │                    │  2. POST /auth/    │
       │                    │     iframe-token   │
       │                    │  (Basic Auth)      │
       │                    │───────────────────>│
       │                    │                    │
       │                    │  3. Returns OTT    │
       │                    │<───────────────────│
       │                    │                    │
       │  4. Return OTT     │                    │
       │<───────────────────│                    │
       │                    │                    │
       │  5. POST /auth/exchange (ott)           │
       │────────────────────────────────────────>│
       │                    │                    │
       │  6. access_token + refresh_token        │
       │<────────────────────────────────────────│
       │                    │                    │
       │  7. API calls with access_token         │
       │────────────────────────────────────────>│

​
Step 1: Get a one-time token (OTT)

Your backend calls the WhataBot API with Basic Auth using the client credentials. This returns a one-time token that is valid for 60 seconds. 
curl -X POST https://api.whatabot.app/api/auth/iframe-token \
  -H "Authorization: Basic $(echo -n 'clientId:clientSecret' | base64)" \
  -H "Content-Type: application/json"
Response: 
{
  "ott": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
The OTT expires after 60 seconds. Your frontend must exchange it before it expires. Each OTT can only be used once.

​
Why use a one-time token?

The OTT pattern ensures that the clientSecret is never exposed in frontend code. Your backend holds the secret and generates short-lived, single-use tokens that the frontend can safely pass to the iframe.

​
Integration example

Here is a complete example showing how to integrate the embedded editor into a web application:

​
Backend (Node.js)

// Your backend endpoint that the frontend calls to get an OTT
app.post('/api/whatabot/ott', async (req, res) => {
  const clientId = process.env.WHATABOT_CLIENT_ID;
  const clientSecret = process.env.WHATABOT_CLIENT_SECRET;

  const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');

  const response = await fetch('https://api.whatabot.app/api/auth/iframe-token', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${credentials}`,
      'Content-Type': 'application/json',
    },
  });

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

​
Frontend (HTML/JavaScript)

<iframe id="whatabot-editor" src="https://flow.whatabot.app" style="width: 100%; height: 600px; border: none;"></iframe>

<script>
async function initEditor() {
  // 1. Get OTT from your backend
  const response = await fetch('/api/whatabot/ott', { method: 'POST' });
  const { ott } = await response.json();

  // 2. Pass OTT to the iframe via postMessage
  const iframe = document.getElementById('whatabot-editor');
  iframe.addEventListener('load', () => {
    iframe.contentWindow.postMessage({ type: 'auth', ott }, 'https://flow.whatabot.app');
  });
}

initEditor();
</script>