Skip to main content

Documentation Index

Fetch the complete documentation index at: https://aimnahai.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Aimna Website Widget

The Aimna embeddable website widget is a production-ready, customizable, and secure widget for websites, powered by the Aimna API. The widget is embeddable via a single <script> tag and uses the Aimna public key system, allowing direct API calls from the frontend — no backend proxy required. The widget supports two modes:
  • Chat Widget: Text-based conversations — requires a chat agent
  • Callback Widget: Phone-based conversations — requires a voice agent
The chat widget only works with chat agents. Voice agents do not support the chat widget. If you have a voice agent and want to add a widget to your website, use the callback widget instead — it collects the visitor’s phone number and initiates a voice call with your agent.

​
Prerequisites

Before embedding either widget, you’ll need:
  1. Create an Agent:
    • For chat widget: Create a chat agent using the Create Chat Agent guide
    • For callback widget: Create a voice agent to handle phone conversations
  2. Get Your Credentials:
    • Your Aimna Public Key
    • Your agent ID (chat agent ID for chat widget, voice agent ID for callback widget)
    • For callback widget: Your Aimna phone number

​
Chat Widget

The chat widget provides text-based conversations through a chat interface. This widget requires a chat agent — it does not work with voice agents.

​
Setup

Add the following script tag to your HTML, within the <head> tag: 
<script
    id="aimna-widget"
    src="https://api.aimna.app/static/widget/widget.js"
    data-public-key="YOUR_AIMNA_PUBLIC_KEY"
    data-agent-id="YOUR_CHAT_AGENT_ID"
    data-agent-version="YOUR_AGENT_VERSION"
    data-title="YOUR_CUSTOM_TITLE"
    data-logo-url="YOUR_LOGO_URL"
    data-color="YOUR_CUSTOM_COLOR"
    data-bot-name="YOUR_BOT_NAME"
    data-position="bottom-right"
    data-popup-message="YOUR_POPUP_MESSAGE"
    data-show-ai-popup="true"
    data-show-ai-popup-time="5"
    data-auto-open="false"
    data-dynamic='{"key": "value"}'
    data-recaptcha-key="YOUR_GOOGLE_RECAPTCHA_SITE_KEY"
></script>

​
Chat Widget Attributes

Required:
  • data-public-key - Your Aimna public key
  • data-agent-id - Your chat agent ID
Optional:
  • data-agent-version - Agent version (if unset, uses latest version)
  • data-title - Custom chat window title
  • data-logo-url - URL of your logo image
  • data-color - Hex color code for widget theme (e.g., "#FFA07A")
  • data-bot-name - Bot name for popup messages
  • data-position - Widget position: "bottom-right" (default) or "bottom-left"
  • data-popup-message - Popup message before users open chat
  • data-show-ai-popup - Set to "true" to enable popup messages
  • data-show-ai-popup-time - Seconds to delay before showing popup (default: 0)
  • data-auto-open - Set to "true" to auto-open chat widget on page load
  • data-dynamic - JSON string with dynamic variables for the chat agent
  • data-recaptcha-key - Google reCAPTCHA v3 site key for bot protection (Note: Only reCAPTCHA v3 is supported)

​
reCAPTCHA Protection

The chat widget supports Google reCAPTCHA v3 for bot protection. Important: Only reCAPTCHA v3 is supported. To enable reCAPTCHA:
  1. Include the Google reCAPTCHA v3 script in your HTML <head> tag:
<script src="https://www.google.com/recaptcha/api.js?render=YOUR_GOOGLE_RECAPTCHA_SITE_KEY"></script>
  1. Add the data-recaptcha-key attribute to your widget script with your reCAPTCHA v3 site key
  2. Enable reCAPTCHA protection for your public key in the Aimna Public Keys settings

​
How Chat Widget Works

  1. User clicks the chat widget button (displays a chat icon)
  2. Chat interface opens in a modal window
  3. User types messages and receives responses from the chat agent
  4. Chat sessions are automatically handled and persisted in localStorage
  5. If reCAPTCHA is enabled, bot protection is automatically applied

​
Testing Chat Widget

After adding the widget to your website:
  1. Load your website
  2. Click the floating button (bottom right, chat icon)
  3. Start a conversation with your agent

​
Example: Chat Widget

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Aimna Chat Widget Example</title>
    <script src="https://www.google.com/recaptcha/api.js?render=YOUR_GOOGLE_RECAPTCHA_SITE_KEY"></script>
    <script
      id="aimna-widget"
      src="https://api.aimna.app/static/widget/widget.js"
      data-public-key="pk_xxxxxxxxxxxxxxxxxxxxx"
      data-agent-id="agent_xxxxxxxxxxxxxxxxxxx"
      data-agent-version="0"
      data-title="Chat with us!"
      data-recaptcha-key="YOUR_GOOGLE_RECAPTCHA_SITE_KEY"
    ></script>
  </head>
  <body></body>
</html>

​
Callback Widget

The callback widget collects user information and initiates a phone call instead of a chat session. This widget requires a voice agent — use this if you want to add a widget to your website for a voice agent.

​
Setup

Add the following script tag to your HTML, within the <head> tag: 
<script
  id="aimna-widget"
  src="https://api.aimna.app/static/widget/widget.js"
  data-public-key="YOUR_AIMNA_PUBLIC_KEY"
  data-agent-id="YOUR_VOICE_AGENT_ID"
  data-widget-type="callback"
  data-phone-number="YOUR_AIMNA_PHONE_NUMBER"
  data-title="Request a Call"
  data-countries="US,CA,GB"
  data-tc="https://yoursite.com/terms"
  data-color="#FFA07A"
  data-recaptcha-key="YOUR_GOOGLE_RECAPTCHA_SITE_KEY"
></script>

​
Callback Widget Attributes

Required:
  • data-public-key - Your Aimna public key
  • data-agent-id - Your voice agent ID (not chat agent)
  • data-widget-type="callback" - Enables callback mode
  • data-phone-number - Your Aimna phone number that will make the outbound call
Optional:
  • data-title - Custom widget title
  • data-color - Hex color code for widget theme
  • data-position - Widget position: "bottom-right" (default) or "bottom-left"
  • data-countries - Comma-separated country codes for country selector (e.g., "US,CA,GB")
  • data-tc - URL to your terms and conditions page
  • data-recaptcha-key - Google reCAPTCHA v3 site key for bot protection

​
How Callback Widget Works

The callback widget supports the same reCAPTCHA v3 protection as the chat widget. To enable it, follow the instructions in the reCAPTCHA Protection section above.
  1. User clicks the callback widget button (displays a phone icon)
  2. A form appears collecting:
    • Name (required)
    • Phone number (required)
    • Email (optional)
    • Terms & conditions agreement checkbox (if data-tc is set)
  3. User submits the form
  4. If reCAPTCHA is enabled, the form submission is validated
  5. The widget creates a phone call using the Aimna API
  6. User receives a call from your specified phone number
  7. The conversation is handled by your configured voice agent

​
Testing Callback Widget

After adding the widget to your website:
  1. Load your website
  2. Click the floating button (bottom right, phone icon)
  3. Fill out the contact form
  4. Submit and wait for the phone call

​
Example: Callback Widget

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Aimna Callback Widget Example</title>
    <script src="https://www.google.com/recaptcha/api.js?render=YOUR_GOOGLE_RECAPTCHA_SITE_KEY"></script>
    <script
      id="aimna-widget"
      src="https://api.aimna.app/static/widget/widget.js"
      data-public-key="pk_xxxxxxxxxxxxxxxxxxxxx"
      data-agent-id="agent_xxxxxxxxxxxxxxxxxxx"
      data-widget-type="callback"
      data-phone-number="+15551234567"
      data-title="Request a Call"
      data-countries="US,CA,GB"
      data-tc="https://example.com/terms"
      data-color="#FFA07A"
      data-recaptcha-key="YOUR_GOOGLE_RECAPTCHA_SITE_KEY"
    ></script>
  </head>
  <body></body>
</html>

​
Widget Behavior Summary

WidgetAgent TypeIconBehavior
Chat WidgetChat agentChat iconOpens chat interface for text conversations
Callback WidgetVoice agentPhone iconOpens form to collect contact info and initiates a phone call