Embeddable Tax Nigeria AI WidgetCopy Anchor Link

The Tax Nigeria Chat Widget allows businesses, fintechs, payroll providers, and accounting firms to embed Nigeria's leading tax intelligence agent onto any web page or SaaS application.

The widget is lightweight (under 15KB gzipped), requires zero third-party dependencies, runs asynchronously, and provides instant answers grounded in current Nigerian tax legislation (including the Nigeria Tax Act 2025/2026, CITA, PITA, VAT, and WHT regulations).

Key CapabilitiesCopy Anchor Link

• Instant 1-Line Drop-In: Add a single <script> tag before your closing </body> tag to activate the assistant.
• Dual Operation Pathways: Choose between instant Anonymous Drop-In (zero setup) or Registered Dashboard Widgets (domain-whitelisted with custom quotas).
• Grounded Nigerian Tax Knowledge: Pre-trained and retrieval-augmented across Personal Income Tax (PAYE), Company Income Tax (CIT), Value Added Tax (VAT), and Withholding Tax (WHT).
• Brand Customization: Customize primary brand colors, header titles, welcome greetings, and screen position (bottom-right or bottom-left).
• Custom Starter Prompts: Guide your users with industry-specific starter questions (for Payroll, Fintech, Real Estate, or E-commerce).
• Proactive Nudge Bubble: Automatically presents a non-intrusive floating speech bubble to invite visitor engagement.
• Programmatic JavaScript API: Open, close, toggle, or update questions dynamically via window.TaxNGWidget.
• Cross-Frame Lifecycle Events: Listen for load, expand, collapse, and theme changes via standard HTML5 window.addEventListener('message').

Integration Modes: Anonymous vs RegisteredCopy Anchor Link

The Tax Nigeria Widget provides two distinct operating modes designed to balance frictionless testing with enterprise security:

Mode 1: Anonymous Drop-In (Zero Setup)Copy Anchor Link

The Anonymous Drop-In mode is the fastest way to get started. You do not need to register an account or configure any backend credentials.

How It WorksCopy Anchor Link

• Add the public script tag to your web page HTML.
• Your visitors receive 5 free tax calculations and legal queries per 24 hours (tracked fairly per visitor IP and device).
• Configure branding, titles, and starter questions statically using HTML data-* attributes.

Code Examples (Mode 1)Copy Anchor Link

<!-- Place before closing </body> tag -->
<script 
  src="https://taxnigeria.ng/widget/taxng-widget.js" 
  data-position="bottom-right" 
  data-primary-color="#066738"
  data-title="Tax Nigeria Assistant"
  data-greeting="Hello! Ask any question regarding PAYE, CIT, or VAT."
  data-nudge="true"
></script>

Mode 2: Registered Dashboard Widget (Domain-Protected)Copy Anchor Link

Mode 2 is recommended for all production websites, client portals, and SaaS platforms. It attaches your unique data-widget-id to protect your platform against unauthorized embedding and provides deep control over styling and visitor limits.

Why Register Your Widget?Copy Anchor Link

1. Domain Whitelisting (Anti-Hotlinking): Only authorized domains (e.g. acmepayroll.ng, app.mycompany.com, localhost:3000) can initialize your widget. Unauthorized third parties attempting to copy your embed tag onto their own websites will receive HTTP 403 Forbidden.
2. Higher Visitor Allowances: Increase the daily visitor question limit from the default 5 up to 100 questions per visitor per day.
3. Live Remote Styling: Change brand colors, titles, greetings, launcher position, and starter prompts directly in your dashboard without touching your codebase or deploying changes.
4. Instant Pause / Resume: Deactivate a live widget immediately from your dashboard if needed.

Registration StepsCopy Anchor Link

Code Examples (Mode 2)Copy Anchor Link

<!-- Place before closing </body> tag -->
<script 
  src="https://taxnigeria.ng/widget/taxng-widget.js" 
  data-widget-id="wid_live_8f3a9e12"
></script>

HTML Data Attributes ReferenceCopy Anchor Link

When using Mode 1 (Anonymous) or overriding settings locally in Mode 2, use the following data-* attributes on the <script> tag:

Custom Starter PromptsCopy Anchor Link

Starter prompts allow you to suggest relevant questions tailored to your user demographic. You can configure them in the dashboard (Mode 2) or supply them via script tag attributes (Mode 1).

Option A: JSON Array SyntaxCopy Anchor Link

<script 
  src="https://taxnigeria.ng/widget/taxng-widget.js"
  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 in Lagos?"
  ]'
></script>

Option B: Pipe-Separated SyntaxCopy Anchor Link

<script 
  src="https://taxnigeria.ng/widget/taxng-widget.js"
  data-mode="chat"
  data-starter-prompts="What is Withholding Tax? | How do I register for VAT? | What are the 2026 PAYE bands?"
></script>

JavaScript Programmatic APICopy Anchor Link

Control the widget from your own navigation bars, CTA buttons, or customer support links via the global window.TaxNGWidget object.

Example: Binding to a Custom Support ButtonCopy Anchor Link

// Attach to a custom "Ask Tax Specialist" button in your navbar
document.getElementById('nav-tax-help-btn').addEventListener('click', () => {
  if (window.TaxNGWidget) {
    window.TaxNGWidget.setStarterPrompts([
      "Explain the tax deductions for this invoice",
      "What is the applicable VAT rate in Nigeria?",
      "How to remit withholding tax to FIRS"
    ]);

    window.TaxNGWidget.open();
  }
});

Cross-Frame Lifecycle Events (postMessage)Copy Anchor Link

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

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 initialized and ready');
      break;

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

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

    case 'taxng-widget:theme-change':
      console.log('Widget theme switched to:', event.data.theme);
      break;
  }
});

Security & Domain WhitelistingCopy Anchor Link

Origin & Referer VerificationCopy Anchor Link

In Mode 2, every configuration fetch and chat stream verifies the Origin and Referer request headers against your allowed domains list.

• If a request originates from an unlisted website, the API responds with HTTP 403 and the widget displays a polite notice.
• Whitelist patterns support exact root domains (acmepayroll.ng), explicit ports (localhost:3000), and wildcard subdomains (*.acmepayroll.ng).

Content Security Policy (CSP)Copy Anchor Link

The widget endpoint transmits framing headers allowing embedding across all standard HTTPS origins:

Content-Security-Policy: frame-ancestors 'self' * https: http:;

Local Development NoticeCopy Anchor Link

Modern web browsers enforce strict security policies for local file:/// URLs that prevent cross-origin iframe communication. When testing locally, always run a local HTTP development server (such as localhost:3000, npx serve, Vite, or VS Code Live Server) rather than opening HTML files directly from disk.