DrGUI Documentation SDK v5.4 -- Integration, API reference, and configuration

Getting Started

DrGUI is an AI-powered website navigation and onboarding overlay that guides your users through any page with voice-enabled, multilingual assistance. It embeds as a single script tag and works with any framework or static site -- no build step required.

Quick setup

Sign up at drgui.in to get your API token.
Add one script tag to your website (before </body> or with defer):

<script src="https://drgui.in/guidr-sdk.js"
        data-token="YOUR_TOKEN"
        defer></script>

That is it. The DrGUI widget appears in the bottom-right corner of your site. Users can type or speak questions, and the AI guides them through forms, navigation, and content -- in 9 Indian languages.

Integration

Auto-init (recommended)

The simplest approach. The SDK reads data-* attributes from the script tag and initializes automatically when the DOM is ready.

<script src="https://drgui.in/guidr-sdk.js"
        data-token="YOUR_TOKEN"
        data-theme="dark"
        data-position="bottom-right"
        data-color="#01696f"
        data-welcome="Hi! How can I help you today?"
        defer></script>

The SDK detects its own script element by looking for a <script> with a data-token attribute whose src contains guidr or drgui. The API endpoint is derived automatically from the script's origin.

Manual init

For more control, load the script without data-token and call DrGUI.init() yourself. The SDK exposes both DrGUI and GuidR as global aliases.

<script src="https://drgui.in/guidr-sdk.js" defer></script>
<script>
  document.addEventListener('DOMContentLoaded', function () {
    DrGUI.init({
      apiEndpoint: 'https://drgui.in/api/guide',
      token: 'YOUR_TOKEN',
      theme: 'auto',
      position: 'bottom-right',
      primaryColor: '#01696f',
      welcomeMessage: 'Hi! How can I help you today?'
    });
  });
</script>

Data attributes

When using auto-init, these data-* attributes configure the widget:

Attribute	Maps to	Default
`data-token`	`token`	required
`data-theme`	`theme`	`auto`
`data-position`	`position`	`bottom-right`
`data-color`	`primaryColor`	`#01696f`
`data-welcome`	`welcomeMessage`	Hi! How can I help you today?

Configuration

All options can be passed to DrGUI.init(config):

Option	Type	Default	Description
`apiEndpoint`	string	`/api/guide`	URL of the DrGUI guidance API. Auto-derived from script src when using auto-init.
`token`	string	required	Your API authentication token from the DrGUI dashboard.
`theme`	string	`auto`	Widget color scheme: `light`, `dark`, or `auto` (follows system preference).
`position`	string	`bottom-right`	Widget position: `bottom-right` or `bottom-left`.
`primaryColor`	string	`#01696f`	Accent color for the widget (hex). Used for the FAB button and highlights.
`welcomeMessage`	string	Hi! How can I help you today?	Initial message shown when the widget opens. Set to empty string to disable.

Excluding elements

Add the data-guidr-ignore attribute to any form field or interactive element you want the SDK to skip during page scanning. The AI will not see or reference these elements.

<!-- This field will be invisible to DrGUI -->
<input type="hidden" name="csrf_token" data-guidr-ignore />
<input type="text" name="internal_ref" data-guidr-ignore />

Site Description

A site description provides the AI with context about your website, your business, and what users can do on your site. This improves the quality and relevance of AI guidance significantly.

How to add during signup

When you register for DrGUI, you provide your website URL. After signup, you can add a detailed site description from the dashboard or via the API.

Updating via API

Use the POST /api/client/site endpoint to add or update your site description:

curl -X POST https://drgui.in/api/client/site \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "https://yoursite.com",
    "description": "YourSite is an online lending platform...",
    "clientName": "YourSite"
  }'

To retrieve your current site description:

curl https://drgui.in/api/client/site?origin=https://yoursite.com \
  -H "Authorization: Bearer YOUR_TOKEN"

Tips for writing good descriptions

Describe what your website does in 2-3 sentences (e.g., "NeoBank is a digital banking platform for small businesses").
List the main user flows: signup, KYC, loan application, payment, etc.
Mention any domain-specific terminology the AI should know (e.g., "PAN", "Aadhaar", "NACH mandate").
Keep it under 5000 characters. Concise descriptions work better than long ones.
You can set a per-origin description (for staging vs production) or a global one (origin *).

API Reference

Base URL: https://drgui.in. All request and response bodies are JSON. Authenticated endpoints require the Authorization: Bearer YOUR_TOKEN header. Admin endpoints require a legacy server token set in the GUIDR_API_TOKENS environment variable.

Public Endpoints

These endpoints do not require authentication. They are rate-limited per IP.

POST /api/register No auth

Request Body

{
  "clientName": "Acme Corp",       // required, max 100 chars
  "email": "dev@acme.com",         // required, valid email
  "password": "securepass123",     // required, min 8 chars
  "website": "https://acme.com"   // optional
}

Response (201)

{
  "token": "abcdef1234567890...",
  "expiresAt": "2026-04-22",
  "usageLimit": 500,
  "plan": "trial",
  "requiresVerification": true
}

Example

curl -X POST https://drgui.in/api/register \
  -H "Content-Type: application/json" \
  -d '{"clientName":"Acme","email":"dev@acme.com","password":"secure123","website":"https://acme.com"}'

POST /api/login No auth

Authenticate with email and password. Returns the API token and account details.

Request Body

{
  "email": "dev@acme.com",
  "password": "securepass123"
}

Response (200)

{
  "token": "abcdef1234567890...",
  "plan": "trial",
  "expiresAt": "2026-04-22",
  "clientName": "Acme Corp",
  "daysRemaining": 7
}

Example

curl -X POST https://drgui.in/api/login \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@acme.com","password":"secure123"}'

POST /api/verify-email No auth

Verify your email address with the 6-digit code sent during registration.

Request Body

{
  "email": "dev@acme.com",
  "code": "123456"
}

Response (200)

{
  "success": true,
  "message": "Email verified. You can now log in."
}

Example

curl -X POST https://drgui.in/api/verify-email \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@acme.com","code":"123456"}'

POST /api/resend-verification No auth

Resend the email verification code. Rate limited to 3 requests per 5 minutes.

Request Body

{
  "email": "dev@acme.com"
}

Response (200)

{
  "success": true,
  "message": "Verification code resent"
}

Example

curl -X POST https://drgui.in/api/resend-verification \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@acme.com"}'

POST /api/forgot-password No auth

Request a password reset code. Always returns success to avoid revealing whether the email exists.

Request Body

{
  "email": "dev@acme.com"
}

Response (200)

{
  "success": true,
  "message": "If an account with that email exists, a reset code has been sent."
}

Example

curl -X POST https://drgui.in/api/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@acme.com"}'

POST /api/reset-password No auth

Reset your password using the 6-digit code from the forgot-password email.

Request Body

{
  "email": "dev@acme.com",
  "code": "654321",
  "newPassword": "newsecurepass456"
}

Response (200)

{
  "success": true,
  "message": "Password reset successfully. You can now log in with your new password."
}

Example

curl -X POST https://drgui.in/api/reset-password \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@acme.com","code":"654321","newPassword":"newsecurepass456"}'

POST /api/enquiry No auth

Submit a contact/enquiry form. Rate limited to 5 per hour per IP.

Request Body

{
  "name": "Jane Doe",            // required, max 100 chars
  "email": "jane@example.com",   // required, max 254 chars
  "subject": "Integration help", // optional, max 100 chars
  "message": "I need help..."    // required, max 5000 chars
}

Response (201)

{
  "success": true
}

Example

curl -X POST https://drgui.in/api/enquiry \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane","email":"jane@example.com","message":"Question about pricing"}'

Authenticated Endpoints

These require Authorization: Bearer YOUR_TOKEN in the request header.

POST /api/guide Bearer

Main guidance endpoint. Sends user task and page context to the AI, returns navigation steps and/or a conversational response. This is the core endpoint the SDK calls.

Request Body

{
  "task": "How do I fill out the KYC form?",
  "pageMap": {
    "url": "https://yoursite.com/kyc",
    "title": "KYC Verification",
    "fields": [...],
    "actions": [...],
    "sections": [...]
  },
  "siteContext": {},
  "lang": "en-IN",
  "currentStep": 0,
  "sessionId": "uuid-string",
  "completedSelectors": []
}

Response (200)

{
  "steps": [
    {
      "fieldSelector": "#pan-number",
      "action": "fill",
      "hint": "Enter your 10-character PAN number",
      "example": "ABCDE1234F"
    }
  ],
  "summary": "Let me help you complete the KYC form.",
  "flowStatus": "in_progress"
}

Example

curl -X POST https://drgui.in/api/guide \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task":"Help me fill this form","lang":"en-IN"}'

POST /api/tts Bearer

Convert text to speech using Microsoft Edge neural TTS voices. Returns base64-encoded MP3 audio. Supports all 9 Indian languages with automatic script detection.

Request Body

{
  "text": "Welcome to the KYC form.",   // required, max 2000 chars
  "lang": "en-IN"                        // optional, auto-detected from script
}

Response (200)

{
  "audio": "SUQzBAAAAAAAI1RTU0...",  // base64 MP3
  "format": "mp3"
}

Example

curl -X POST https://drgui.in/api/tts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello, how can I help?","lang":"en-IN"}'

GET /api/token/info Bearer

Get information about your token: plan, usage, expiry, and status.

Response (200)

{
  "plan": "trial",
  "expiresAt": "2026-04-22",
  "usageCount": 42,
  "usageLimit": 500,
  "active": true,
  "daysRemaining": 5
}

Example

curl https://drgui.in/api/token/info \
  -H "Authorization: Bearer YOUR_TOKEN"

GET /api/account Bearer

Get full account details including name, email, plan, usage, sites, and creation date.

Response (200)

{
  "clientName": "Acme Corp",
  "email": "dev@acme.com",
  "plan": "trial",
  "usageCount": 42,
  "usageLimit": 500,
  "expiresAt": "2026-04-22",
  "daysRemaining": 5,
  "sites": ["https://acme.com"],
  "createdAt": "2026-04-15"
}

Example

curl https://drgui.in/api/account \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /api/change-password Bearer

Change your account password. Requires the current password for verification.

Request Body

{
  "currentPassword": "oldpass123",
  "newPassword": "newsecurepass456"   // min 8, max 128 chars
}

Response (200)

{
  "success": true
}

Example

curl -X POST https://drgui.in/api/change-password \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"currentPassword":"oldpass","newPassword":"newpass123"}'

GET /api/analytics Bearer

Get detailed analytics for your token: daily interactions, language breakdown, top pages (last 30 days).

Response (200)

{
  "daily": {
    "2026-04-15": { "interactions": 12, "sessions": 3 }
  },
  "languages": { "en-IN": 8, "hi-IN": 4 },
  "topPages": { "/kyc": 7, "/dashboard": 5 },
  "totalInteractions": 42,
  "totalSessions": 10,
  "lastActive": "2026-04-15T10:30:00.000Z"
}

Example

curl https://drgui.in/api/analytics \
  -H "Authorization: Bearer YOUR_TOKEN"

GET /api/analytics/summary Bearer

Quick summary stats for dashboard cards: today's interactions, usage percentage, days remaining.

Response (200)

{
  "todayInteractions": 5,
  "totalInteractions": 42,
  "todaySessions": 2,
  "plan": "trial",
  "usageLimit": 500,
  "usageCount": 42,
  "usagePercent": 8,
  "daysRemaining": 5,
  "expiresAt": "2026-04-22"
}

Example

curl https://drgui.in/api/analytics/summary \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /api/client/site Bearer

Add or update your site description. This context is injected into AI prompts to improve guidance quality.

Request Body

{
  "origin": "https://yoursite.com",  // optional, omit for global
  "description": "YourSite is...",   // required, max 5000 chars
  "clientName": "YourSite"           // optional, max 100 chars
}

Response (200)

{
  "success": true,
  "site": {
    "description": "YourSite is...",
    "clientName": "YourSite",
    "updatedAt": "2026-04-15T10:00:00.000Z"
  }
}

Example

curl -X POST https://drgui.in/api/client/site \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description":"Our lending platform helps SMEs get business loans."}'

GET /api/client/site Bearer

Retrieve the site description for a given origin (or the global fallback).

Query Parameters

?origin=https://yoursite.com   // optional, defaults to *

Response (200)

{
  "site": {
    "description": "YourSite is...",
    "clientName": "YourSite",
    "updatedAt": "2026-04-15T10:00:00.000Z"
  }
}

Example

curl "https://drgui.in/api/client/site?origin=https://yoursite.com" \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /api/payment/create-order Bearer

Create a Razorpay order for plan upgrade. Returns the order ID and Razorpay key for client-side checkout.

Request Body

{
  "plan": "starter"   // "starter" (Rs 1,999) or "growth" (Rs 7,999)
}

Response (200)

{
  "orderId": "order_abc123",
  "amount": 199900,
  "currency": "INR",
  "key": "rzp_..."
}

Example

curl -X POST https://drgui.in/api/payment/create-order \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan":"starter"}'

POST /api/payment/verify Bearer

Verify a Razorpay payment and upgrade the token's plan. Validates the HMAC SHA256 signature.

Request Body

{
  "razorpay_order_id": "order_abc123",
  "razorpay_payment_id": "pay_xyz789",
  "razorpay_signature": "hmac...",
  "plan": "starter"
}

Response (200)

{
  "success": true,
  "plan": "starter",
  "usageLimit": 2000,
  "expiresAt": "2026-05-15"
}

Example

curl -X POST https://drgui.in/api/payment/verify \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"razorpay_order_id":"order_abc","razorpay_payment_id":"pay_xyz","razorpay_signature":"sig","plan":"starter"}'

Admin Endpoints

These require a legacy admin token (set in GUIDR_API_TOKENS env var). Standard user tokens will receive a 403 Forbidden response.

GET /api/admin/clients Admin

List all registered clients with their plan, usage, status, and expiry.

Response (200)

{
  "clients": [
    {
      "id": "abc123def456",
      "clientName": "Acme Corp",
      "email": "dev@acme.com",
      "plan": "trial",
      "usageCount": 42,
      "usageLimit": 500,
      "expiresAt": "2026-04-22",
      "createdAt": "2026-04-15",
      "active": true,
      "status": "active",
      "sites": ["https://acme.com"]
    }
  ]
}

Example

curl https://drgui.in/api/admin/clients \
  -H "Authorization: Bearer ADMIN_TOKEN"

POST /api/admin/client/update Admin

Update a client's plan, usage limit, expiry date, or active status.

Request Body

{
  "clientId": "abc123def456",    // required (first 12 chars of token hash)
  "plan": "starter",             // optional
  "usageLimit": 2000,            // optional
  "expiresAt": "2026-05-15",    // optional
  "active": true                 // optional
}

Response (200)

{
  "success": true,
  "client": {
    "id": "abc123def456",
    "clientName": "Acme Corp",
    "email": "dev@acme.com",
    "plan": "starter",
    "usageLimit": 2000,
    "expiresAt": "2026-05-15",
    "active": true
  }
}

Example

curl -X POST https://drgui.in/api/admin/client/update \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"clientId":"abc123def456","plan":"starter","usageLimit":2000}'

GET /api/admin/stats Admin

Aggregated platform statistics: total clients, active trials, paid clients, interactions, and revenue.

Response (200)

{
  "totalClients": 25,
  "activeTrials": 18,
  "paidClients": 5,
  "expiredClients": 2,
  "todayInteractions": 120,
  "monthInteractions": 3400,
  "revenue": 25995,
  "starterCount": 3,
  "growthCount": 2
}

Example

curl https://drgui.in/api/admin/stats \
  -H "Authorization: Bearer ADMIN_TOKEN"

GET /api/admin/enquiries Admin

List all contact form enquiries.

Response (200)

{
  "enquiries": [
    {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "subject": "Integration help",
      "message": "I need help...",
      "createdAt": "2026-04-15T10:00:00.000Z"
    }
  ]
}

Example

curl https://drgui.in/api/admin/enquiries \
  -H "Authorization: Bearer ADMIN_TOKEN"

POST /api/admin/enquiry/read Admin

Mark an enquiry as read (or unread).

Request Body

{
  "index": 0,       // enquiry array index
  "read": true      // true to mark as read, false to unmark
}

Response (200)

{
  "success": true
}

Example

curl -X POST https://drgui.in/api/admin/enquiry/read \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"index":0,"read":true}'

Other

GET /api/health No auth

Health check endpoint. Returns server status and uptime.

Response (200)

{
  "status": "ok",
  "uptime": 86400,
  "timestamp": "2026-04-15T10:00:00.000Z"
}

Example

curl https://drgui.in/api/health

SDK Methods

The SDK exposes a global object available as both DrGUI and GuidR. All methods are identical on both aliases.

Method / Property	Description
`DrGUI.init(config)`	Initialize the widget with a configuration object. Builds the panel (using Shadow DOM for style isolation), loads site context, and shows the welcome message. Returns the `DrGUI` object for chaining.
`DrGUI.open()`	Open the chat panel and hide the floating action button.
`DrGUI.close()`	Close the chat panel and show the floating action button.
`DrGUI.destroy()`	Completely remove the widget from the DOM. Cleans up all event listeners, stops voice and guidance, removes the Shadow DOM host element. Can be re-initialized with `init()` afterwards.
`DrGUI.sendMessage(text, isFollowUp)`	Send a message to the AI as if the user typed it. If `isFollowUp` is `true`, the message is treated as a continuation of the current task (no user bubble shown, same task context). Opens the panel automatically.
`DrGUI.scanPage()`	Scan the current page and return the page map: form fields (with selectors, types, labels), clickable actions (buttons, links, tabs), content sections, and multi-step form state. This is what gets sent to the AI as context.
`DrGUI.version`	SDK version string (currently `"v5.4"`).

Usage example

// Initialize
DrGUI.init({
  apiEndpoint: 'https://drgui.in/api/guide',
  token: 'YOUR_TOKEN',
  theme: 'dark'
});

// Open the panel programmatically
DrGUI.open();

// Send a message on behalf of the user
DrGUI.sendMessage('How do I apply for a loan?');

// Later, clean up
DrGUI.destroy();

Voice Mode

How it works

DrGUI supports full voice interaction. Users can click the microphone icon in the chat panel to speak their question instead of typing. The SDK uses the browser's Web Speech API for speech-to-text (STT) and Microsoft Edge neural TTS for text-to-speech responses.

Voice chat mode provides a hands-free, conversational experience. When active, the SDK continuously listens and responds with spoken audio. It also supports wake words: say "Help" or "GuidR" to activate voice mode from the keyboard.

Supported languages

TTS is available in all 9 languages. STT availability depends on the browser (Chrome and Edge have the broadest support).

Language	Code	TTS Voice
English (India)	`en-IN`	en-US-AriaNeural
Hindi	`hi-IN`	hi-IN-SwaraNeural
Marathi	`mr-IN`	mr-IN-AarohiNeural
Telugu	`te-IN`	te-IN-ShrutiNeural
Malayalam	`ml-IN`	ml-IN-SobhanaNeural
Tamil	`ta-IN`	ta-IN-PallaviNeural
Kannada	`kn-IN`	kn-IN-SapnaNeural
Bengali	`bn-IN`	bn-IN-TanishaaNeural
Gujarati	`gu-IN`	gu-IN-DhwaniNeural

Voice chat vs text chat

Text chat -- The default mode. Users type questions and receive text responses with visual step-by-step overlays on the page.
Voice chat -- Activated via the microphone icon. Users speak their question, the AI responds with both text and spoken audio. The language is auto-detected from the text script (e.g., Devanagari text triggers Hindi TTS).
Both modes produce the same AI guidance. Voice chat simply adds STT input and TTS output on top of the same text pipeline.

Troubleshooting

Widget does not appear

Verify your data-token attribute is set and the token is valid (not expired or over limit).
Open the browser console (F12) and look for errors. Common issues: mixed content (HTTP SDK on HTTPS page), network errors, or CSP blocking.
Make sure the script tag includes defer or is placed before </body>.
If using manual init, ensure DrGUI.init() is called after the DOM is ready.

"I couldn't process that" response

Check that your token is still active: call GET /api/token/info and verify active: true.
If the token is expired or over the usage limit, the AI backend will return an error. Upgrade your plan from the dashboard.
For very long or complex questions, try simplifying. The task field has a 2000-character limit.

No voice / microphone not working

Check browser permissions: the site must have microphone access. Look for the microphone icon in the browser address bar.
Web Speech API works best in Chrome and Edge. Firefox and Safari have limited STT support.
HTTPS is required for microphone access. Voice will not work on http:// pages (except localhost).
If TTS audio does not play, check that the server has Python 3 and the edge-tts package installed.

Trial expired

Free trials last 7 days with 500 interactions.
Log in to the dashboard and upgrade to Starter (Rs 1,999/mo) or Growth (Rs 7,999/mo).
Your token remains the same after upgrade -- no code changes needed.

Need help? Contact us at hello@drgui.in or use the contact form.