Tencent Cloud ADP Chatbot Frontend Deployment Guide

This project provides a third-party chatbot frontend for the Tencent Cloud Agent Development Platform (ADP).

It is built with React, offers real-time chat with the ADP backend, supports both WebSocket and SSE transport, and includes token management along with AI conversation capabilities.

🚀 Quick Deployment

One-click deploy on Vercel

Click below to clone and deploy instantly:

After setting environment variables (see below), press Deploy to go live.

Manual deployment to Vercel

1. Push the project to your own GitHub repository.
2. Log in to Vercel and import the repo.
3. Configure environment variables in the project settings (details below).
4. Click Deploy.

🔧 Environment variables

Set the following variables during deployment:

• TENCENT_SECRET_ID: Tencent Cloud API Secret ID
• TENCENT_SECRET_KEY: Tencent Cloud API Secret Key
• TENCENT_APP_ID: Tencent Cloud App ID

How to obtain the values

:::info[Steps]

1. Open API Key Management.
2. Create a new key pair.
3. Copy the Secret ID and Secret Key.
4. Visit App Management and create an app.
5. In Tencent Cloud ADP go to Application → Publish → API Management and copy the AppKey (App ID). :::

Add the variables in your Vercel project settings:

🌐 Embed on a website

Option 1: Inline iframe

Embed the deployed URL directly:

<iframe
  src="https://adp-chat-ui.vercel.app" <!-- Replace with your deployment URL -->
  style="width: 100%; height: 600px; border: 0;"
  allow="clipboard-write *; microphone; camera"
></iframe>

Adjust the size and styling as needed.

Option 2: Lightweight floating widget

Append the following script to any page to spawn a fixed widget in the lower-right corner:

<script>
(function () {
  var url = 'https://adp-chat-ui.vercel.app'; // Replace with your deployment URL
  var iframe = document.createElement('iframe');
  iframe.src = url;
  iframe.style.cssText = [
    'position:fixed',
    'right:24px',
    'bottom:24px',
    'width:380px',
    'height:600px',
    'border:1px solid #e5e7eb',
    'border-radius:12px',
    'box-shadow:0 10px 30px rgba(0,0,0,.15)',
    'z-index:2147483647',
    'background:#fff'
  ].join(';');
  iframe.setAttribute('allow', 'clipboard-write *; microphone; camera');
  document.body.appendChild(iframe);
})();
</script>

Option 3: Single-line embed (recommended)

The repository includes an optimized embed.min.js under public/. After deployment you can integrate the widget with a single script tag. Highlights:

• 🎨 Matches the primary teal palette (#0d9488)
• ✨ Smooth 0.2s easing for open/close animations
• 🎯 Pixel-perfect 28×28 chat icon
• 🧹 Minimal UI with no redundant chrome
• 💾 Remembers open/minimized state via localStorage

Minimal usage

<script>
  window.adpChatbotConfig = {
    baseUrl: 'https://adp-chat-ui.vercel.app' // Replace with your domain
  };
</script>
<script src="https://adp-chat-ui.vercel.app/embed.min.js" defer></script>

Full configuration example

<script>
  window.adpChatbotConfig = {
    baseUrl: 'https://adp-chat-ui.vercel.app', // Your deployment
    width: 380,
    height: 600,
    right: 24,
    bottom: 24,
    bubbleColor: '#0d9488',
    iframePath: '/',
    allow: 'clipboard-write *; microphone; camera'
  };
</script>
<script src="https://adp-chat-ui.vercel.app/embed.min.js" defer></script>

Programmatic control

// Control the widget from the host page
window.ADPChatbot.open();   // Expand
window.ADPChatbot.close();  // Minimize
window.ADPChatbot.toggle(); // Toggle state

Custom styling

<style>
  /* Override bubble color */
  [data-adp-chatbot="bubble"] {
    background-color: #your-color !important;
  }
  
  /* Override widget size */
  [data-adp-chatbot="wrap"] {
    width: 400px !important;
    height: 650px !important;
  }
</style>

:::warning[Notes]

• The embed never exposes TENCENT_SECRET_ID/KEY; the iframe calls its own /getDemoToken endpoint on the same origin for auth.
• Allow your deployment domain to be framed by other sites (X-Frame-Options should not be DENY). If CSP is enabled, permit the parent domain via frame-ancestors.
• Strict CSP policies must list your deployment under script-src and frame-src.
• For advanced integrations, exchange messages via postMessage between the host page and the iframe. :::

🧪 Local development and testing

Prepare the environment

1. Install Node.js (LTS recommended).

2. Clone the project:

   git clone https://github.com/stvlynn/ADP-Chat-UI.git
   cd ADP-Chat-UI

3. Install dependencies:

   npm install

Configure environment variables

1. Copy .env.local.example to .env.local:

cp .env.local.example .env.local

2. Populate the file:

   TENCENT_SECRET_ID=your_secret_id
   TENCENT_SECRET_KEY=your_secret_key
   TENCENT_APP_ID=your_app_id

Run the dev server

npm run dev

The app runs on http://localhost:9091 by default.

Build for production

npm run build

The output is generated in the dist/ folder.

🔍 Troubleshooting

Common issues

1. Deployment fails

   • Verify environment variables are present and accurate.
   • Make sure the Tencent Cloud credentials have permission to access ADP services.

2. Chatbot does not respond

   • Confirm TENCENT_APP_ID is correct.
   • Ensure the ADP application has been published.

3. Styling breaks after embedding

   • Check that the host site allows iframes.
   • Review CSP rules to confirm external resources are permitted.

Debug tips

• Inspect network requests in browser DevTools.
• Review console logs for runtime errors.
• Use Vercel deployment logs for additional clues.