Atri AI Documentation

Overview

Our embeddable widgets provide the fastest way to add conversational AI to any website. Using simple script tags, you can deploy professional chat interfaces without any complex setup or framework dependencies. Choose between Ping and Flow templates to match your site's needs.

Configuration Parameters

Both widgets support the same set of parameters for consistent configuration across deployment methods.

Required Parameters

data-project-id / projectIdstring

Your project-specific identifier for the AI Chat service. Required for all widget functionality.

Optional Parameters

data-consumer-id / consumerIdstring

Unique identifier for the user. Used to start a fresh conversation and maintain context across sessions.

data-hmac-signature / hmacSignaturestring

HMAC signature for secure consumer authentication. Generated server-side using your project's chat API key.

data-chat-id / chatIdstring

Specific conversation identifier to resume an existing conversation.

Parameter Notes

• For a fresh chat, provide the consumerId and the hmacSignature. To resume an existing chat, provide the chatId.
• If neither consumerId nor chatId is provided, the component will create a temporary anonymous consumer using browser cookies for the session.
• The HMAC signature is needed to verify the identity of the consumer. It should be generated in the backend by passing the consumer ID and your project's chat API key to the API route /hmacSignature.
• The HMAC signature has to be provided if providing a consumer ID. Otherwise, a temporary anonymous consumer ID is created and used for tracking.
• Never expose your API key in client-side requests. Always generate HMAC signatures server-side.
• The /latestConsumerChatId API endpoint can be used to retrieve the latest chat ID for a given consumer.

Implementation Guide

Ping Widget Implementation

The Ping widget automatically appears as a floating chatbot on your website. Simply add the script tag with your configuration:

<script
  src="https://unpkg.com/atri-ai-chat-widget-ping@latest/dist/bundle.js"
  data-project-id="your-project-id"
  data-consumer-id="optional-consumer-id"
  data-hmac-signature="optional-hmac-signature" 
  data-chat-id="optional-chat-id"
  async>
</script>

That's it!

The Ping widget will automatically appear on your website as a floating chatbot. No additional setup required.

Flow Widget Implementation

The Flow widget requires a container element and programmatic mounting. Follow these steps:

Step 1: Create a Container

Add a container element where you want the chat interface to appear:

<div id="chat-widget-container" style="height: 600px; width: 100%;"></div>

Step 2: Load and Mount the Widget

Add the script to load and mount the widget:

<script>
const script = document.createElement('script');
script.src = 'https://unpkg.com/atri-ai-chat-widget-flow@latest/dist/bundle.js';
script.onload = () => {
  const container = document.getElementById('chat-widget-container');
  window.AtriChatFlow?.mount({
    projectId: 'your-project-id',
    consumerId: 'optional-consumer-id',
    hmacSignature: 'optional-hmac-signature',
    chatId: 'optional-chat-id',
    target: container
  });
};
document.head.appendChild(script);
</script>

Complete Implementation Example

Here's a complete HTML page example:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>AI Chat Integration</title>
</head>
<body>
    <h1>My Website with AI Chat</h1>
    
    <!-- Container for the Flow widget -->
    <div id="chat-widget-container" style="height: 600px; width: 100%; border: 1px solid #ccc;"></div>
    
    <!-- Load and mount the widget -->
    <script>
    const script = document.createElement('script');
    script.src = 'https://unpkg.com/atri-ai-chat-widget-flow@latest/dist/bundle.js';
    script.onload = () => {
      const container = document.getElementById('chat-widget-container');
      window.AtriChatFlow?.mount({
        projectId: 'your-project-id',
        consumerId: 'user_12345',
        hmacSignature: 'generated-hmac-signature',
        target: container
      });
    };
    document.head.appendChild(script);
    </script>
</body>
</html>

Advanced Usage

Programmatic Control (Flow Widget)

You can programmatically control the Flow widget after mounting:

// Mount widget to a container
window.AtriChatFlow?.mount({
  projectId: 'your-project-id',
  consumerId: 'user_123',
  hmacSignature: 'generated-hmac-signature',
  target: document.getElementById('chat-container')
});

// Unmount widget from container
const container = document.getElementById('chat-container');
window.AtriChatFlow?.unmount(container);

// Mount multiple widgets to different containers
window.AtriChatFlow?.mount({
  projectId: 'your-project-id',
  consumerId: 'user_123',
  hmacSignature: 'generated-hmac-signature-1', 
  target: document.getElementById('chat-container-1')
});

window.AtriChatFlow?.mount({
  projectId: 'your-project-id',
  consumerId: 'user_456',
  hmacSignature: 'generated-hmac-signature-2',
  target: document.getElementById('chat-container-2')
});

Resuming Conversations

To resume existing conversations, use the chatId parameter:

<!-- Ping Widget - Resume existing chat -->
<script
  src="https://unpkg.com/atri-ai-chat-widget-ping@latest/dist/bundle.js"
  data-project-id="your-project-id"
  data-chat-id="chat_20240711_143052_abc123"
  async>
</script>

<!-- Flow Widget - Resume existing chat -->
<script>
window.AtriChatFlow?.mount({
  projectId: 'your-project-id',
  chatId: 'chat_20240711_143052_abc123',
  target: document.getElementById('chat-container')
});
</script>

Security Best Practices

• Never expose your Chat API key in client-side code or browser requests
• Generate HMAC signatures server-side only using your secure API key
• Use HTTPS for all API calls and widget deployments
• Validate consumer IDs on your backend before generating HMAC signatures
• Implement rate limiting on your HMAC generation endpoints

Implementation Best Practices

• Loading Performance: Use the async attribute on script tags
• Error Handling: Always check if window.AtriChatFlow exists before calling methods
• User Identification: Use consistent consumerId values to maintain user context across sessions
• Container Sizing: Ensure Flow widget containers have defined dimensions (minimum 400px width, 300px height recommended)
• Fallback Handling: Provide fallback contact methods if the widget fails to load

Platform-Specific Integration

WordPress

Add widget scripts to your theme's footer.php file or use a custom HTML block in the WordPress editor. Consider using a plugin to manage HMAC generation.

Shopify

Add scripts to your theme's theme.liquid file before the closing </body> tag. Use Shopify's customer ID as consumerId for authenticated users.

Squarespace

Use Code Injection in Settings to add scripts to the header or footer of your site. For authenticated users, implement server-side HMAC generation.

Static HTML

Add scripts directly to your HTML files before the closing </body> tag. For dynamic users, pair with a backend service for HMAC generation.

Troubleshooting

Widget not appearing: Check browser console for errors, verify projectId is correct, and ensure scripts are loaded properly.

Authentication errors: Verify HMAC signature is generated correctly server-side and consumerId matches the signature.

Chat not resuming: Ensure chatId is valid and belongs to the specified consumer or project.

Flow widget container issues: Verify container element exists and has defined dimensions before mounting.

Embeddable Widget Integration