Tax Nigeria AI Chat Widget - Developer Documentation & Live Demo

1. Quick Start (1-Line Drop-In)

Copy & Paste

Add this script tag right before the closing </body> tag of any web page. The widget initializes asynchronously with zero third-party dependencies.

HTML

<!-- Tax Nigeria AI Assistant Widget -->
<script 
  src="https://www.taxnigeria.com/widget/taxng-widget.js?v=2.5.0" 
  data-mode="chat" 
  data-position="bottom-right" 
  data-primary-color="#066738"
></script>

💡

Instant Activation: Once added, a floating green button appears in the bottom right corner with proactive nudge tooltips and an interactive starter screen.

2. Live Playground & Code Generator

Customize the widget's appearance and starter questions below. The snippet automatically updates with vibrant syntax highlighting so you can copy and deploy your tailored embed code.

Widget Title

Welcome Greeting

Subtitle / Description

Primary Brand Color

Floating Position

Nudge Speech Bubble

Custom Starter Prompts (Pipe-separated or JSON)

Generated HTML Script

3. Framework Guides (React, Next.js, WordPress)

Add before </body> in your index.html:

index.html

<!-- Place before </body> in your layout -->
<script 
  src="https://www.taxnigeria.com/widget/taxng-widget.js?v=2.5.0"
  data-mode="chat"
  data-position="bottom-right"
  data-primary-color="#066738"
></script>

Use Next.js next/script in your root app/layout.tsx:

app/layout.tsx

import Script from 'next/script'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://www.taxnigeria.com/widget/taxng-widget.js?v=2.5.0"
          strategy="afterInteractive"
          data-mode="chat"
          data-position="bottom-right"
          data-primary-color="#066738"
        />
      </body>
    </html>
  )
}

Inject the script dynamically inside a top-level component:

src/App.tsx

import React, { useEffect } from 'react'

export default function App() {
  useEffect(() => {
    const script = document.createElement('script')
    script.src = 'https://www.taxnigeria.com/widget/taxng-widget.js?v=2.5.0'
    script.async = true
    script.setAttribute('data-mode', 'chat')
    script.setAttribute('data-position', 'bottom-right')
    script.setAttribute('data-primary-color', '#066738')
    document.body.appendChild(script)

    return () => {
      document.body.removeChild(script)
    }
  }, [])

  return <div className="app-container">App Content</div>
}

For WordPress, Webflow, Squarespace, or Shopify:

Custom HTML Footer Injection

<!-- In WordPress: Appearance -> Theme File Editor -> footer.php -->
<!-- In Webflow: Project Settings -> Custom Code -> Footer Code -->
<script 
  src="https://www.taxnigeria.com/widget/taxng-widget.js?v=2.5.0" 
  data-mode="chat" 
  data-position="bottom-right" 
  data-primary-color="#066738" 
  data-greeting="Have questions on Nigerian taxes?"
></script>

4. Complete HTML Attributes Reference (data-*)

All configuration is handled declaratively via data attributes on the <script> tag.

Attribute	Type	Default	Description & Usage
data-mode	"chat" \| "redirect"	`"chat"`	chat: opens embedded AI advisory window. redirect: opens `data-redirect-url` in a new tab.
data-position	"bottom-right" \| "bottom-left"	`"bottom-right"`	Screen anchor location for the floating action button and panel.
data-primary-color	string (hex)	`"#066738"`	Primary brand color applied to the floating button, send button, and accents.
data-title	string	`"Tax Nigeria Assistant"`	Header title displayed at the top of the chat panel.
data-greeting	string	`""`	Custom welcome headline shown above starter questions (e.g. `"Welcome to Tax Support"`).
data-subtitle	string	`""`	Custom guidance text displayed directly below the greeting.
data-starter-prompts	JSON \| string	`""`	Custom questions list. Supports JSON array (`'["Q1", "Q2"]'`) or pipe-separated string (`"Q1 \| Q2"`).
data-nudge	"true" \| "false"	`"true"`	Controls whether the proactive floating speech bubble appears beside the button.
data-nudge-text	string	`"Have questions on Nigerian tax? Ask here"`	Custom prompt text inside the proactive speech bubble.
data-redirect-url	string (URL)	`"https://www.taxnigeria.com"`	Destination URL when `data-mode="redirect"`.
data-z-index	string \| number	`"999999"`	Custom CSS z-index to prevent conflict with headers or modals.

5. Custom Starter Prompts

New in v2.5.0

You can customize the initial starter prompt questions to match your industry or audience (e.g. Fintech, Real Estate, E-commerce, Freelancing).

JSON Array Syntax

<script 
  src="https://www.taxnigeria.com/widget/taxng-widget.js?v=2.5.0"
  data-mode="chat"
  data-starter-prompts='[
    "What are the WHT rates on software contracts?",
    "How does VAT apply to digital services in Nigeria?",
    "Can you compute PAYE for remote staff?"
  ]'
></script>

Pipe-Separated Syntax

<script 
  src="https://www.taxnigeria.com/widget/taxng-widget.js?v=2.5.0"
  data-mode="chat"
  data-starter-prompts="What is Withholding Tax? | How do I register for VAT? | What are 2025 PIT rates?"
></script>

6. JavaScript Programmatic API

Control the widget from your own navigation links, CTA buttons, or onboarding flows via the global window.TaxNGWidget object.

Method	Arguments	Description
`window.TaxNGWidget.open()`	None	Opens the chat window and displays the latest messages.
`window.TaxNGWidget.close()`	None	Collapses and closes the floating chat panel.
`window.TaxNGWidget.toggle()`	None	Toggles the open/closed state of the widget panel.
`window.TaxNGWidget.setMode(mode)`	`"chat" \| "redirect"`	Dynamically switches the widget click behavior at runtime.
`window.TaxNGWidget.setStarterPrompts(prompts)`	`string[] \| string`	Updates the starter questions dynamically in real time without reloading.

JavaScript

// Attach to a custom "Ask AI Tax Assistant" button in your navbar
document.getElementById('nav-tax-help-btn').addEventListener('click', () => {
  if (window.TaxNGWidget) {
    // Dynamically customize prompts based on the current page or user role
    window.TaxNGWidget.setStarterPrompts([
      "Explain the tax deductions for this product",
      "What is the VAT rate on this invoice?",
      "How to file withholding tax in Nigeria"
    ]);
    
    // Programmatically open the widget
    window.TaxNGWidget.open();
  }
});

7. Cross-Frame PostMessage Events

The host page can listen for lifecycle events emitted by the embedded chat iframe using standard HTML5 window.addEventListener('message').

JavaScript Listener

window.addEventListener('message', (event) => {
  if (!event.data || typeof event.data !== 'object') return;

  switch (event.data.type) {
    case 'taxng-widget:ready':
      console.log('Tax Nigeria Widget is fully loaded and ready');
      break;

    case 'taxng-widget:close':
      console.log('User collapsed the widget');
      break;

    case 'taxng-widget:expand':
      console.log('Widget expansion state changed:', event.data.expanded);
      break;

    case 'taxng-widget:theme-change':
      console.log('User toggled theme to:', event.data.theme); // 'dark' | 'light'
      break;
  }
});

8. Security, CSP & Hosting FAQ

Best practices for deploying the widget across different environments and production websites.

🔒

Content Security Policy (CSP): The Tax Nigeria widget endpoint sends frame-ancestors 'self' * https: http:; allowing embedding across all standard network protocols.

⚠️

Local Testing (file:/// protocol): Modern browsers (Chrome, Edge, Firefox) reject cross-origin iframes on pages opened directly from disk (e.g. file:///C:/Users/...) for sandbox security. Always run a local HTTP server when testing (e.g. npx serve, VS Code Live Server, or your dev server).

Question	Answer
Is authentication required?	No. The widget works anonymously with zero login or API key required on client websites.
Are there rate limits?	Yes. To ensure high availability and prevent abuse, anonymous users receive 5 free in-depth queries per day per device/IP. A countdown resets at midnight (UTC) with an optional upgrade CTA to TaxNigeria.com.
Which tax laws are supported?	The widget is grounded directly in the Nigeria Tax Act 2025, Companies Income Tax Act (CITA), Personal Income Tax Act (PITA), Value Added Tax Act, and Withholding Tax Regulations.

Embeddable Tax Nigeria AI Widget