Atri AI Logo
SupportSales

How to Integrate AI Chat Using Pre-Built Templates

Step-by-step guide to integrate AI chat functionality into your application using our pre-built React components and JavaScript widgets.

Choose Your Integration Method

We offer two pre-built template types, each available as React components and JavaScript widgets:

Ping Template

Floating chatbot widget for quick support and queries

Best for: Customer support, FAQ, quick information retrieval

Flow Template

Full-screen conversational interface for detailed interactions

Best for: In-depth conversations, complex queries, immersive chat experiences

React Component Integration

For React applications

Step 1: Install the Package

Add the AI Chat templates package to your React project.

  • Run the npm install command to add the package
npm install @atri-ai/templates

Step 2: Import Components and Styles

Import the required component and CSS styles in your React file.

  • Import the CSS file first to ensure proper styling
  • Import the specific template component you want to use
  • Both Ping and Flow templates are available from the same package
import '@atri-ai/templates/styles.css';
import { ChatTemplatePing, ChatTemplateFlow } from '@atri-ai/templates';

Step 3: Configure Your Component

Add the component to your JSX with required configuration parameters.

  • Provide your project ID (required for all integrations)
  • Add consumer ID and HMAC signature for authenticated users
  • Use chat ID to resume existing conversations
  • Leave optional parameters empty for anonymous sessions
// Ping Template - Floating widget
<ChatTemplatePing 
  projectId="your-project-id"
  consumerId="user_12345"
  hmacSignature="hmac-signature-for-the-consumer-id"
/>
// Flow Template - Full-screen interface  
<ChatTemplateFlow 
  projectId="your-project-id"
  consumerId="user_12345"
  hmacSignature="hmac-signature-for-the-consumer-id"
/>
// Resume existing conversation
<ChatTemplateFlow 
  projectId="your-project-id"
  chatId="chat_20240711_143052_abc123"
/>
// Anonymous session
<ChatTemplatePing 
  projectId="your-project-id"
/>

Step 4: Generate HMAC Signatures (For Authenticated Users)

Set up server-side HMAC generation for user authentication.

  • Create a server-side API route to generate HMAC signatures
  • Use your project's chat API key (never expose this client-side)
  • Call the HMAC generation endpoint before rendering the component
  • Pass the generated signature to the component
// Example: Generate HMAC signature server-side
const response = await fetch('/api/generateHmac', {
  method: 'POST',
  body: JSON.stringify({ consumerId: 'user_12345' }),
  headers: { 'Content-Type': 'application/json' }
});
const { hmacSignature } = await response.json();

// Use in component
<ChatTemplatePing 
  projectId="your-project-id"
  consumerId="user_12345"
  hmacSignature={hmacSignature}
/>

JavaScript Widget Integration

For any website or web application

Step 1: Choose Your Template Type

Select between Ping or Flow widget based on your needs.

  • Ping widget: Automatically appears as floating chatbot - no container needed
  • Flow widget: Requires a container element - you control the placement
  • Both widgets support the same authentication parameters

Step 2A: Ping Widget Implementation

Add a simple script tag for the floating chatbot widget.

  • Add the script tag to your HTML before the closing </body> tag
  • Configure using data attributes on the script tag
  • Widget automatically appears when the script loads
  • No additional setup required
<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>

Step 2B: Flow Widget Implementation

Create a container and programmatically mount the Flow widget.

  • Add a container div with defined dimensions where you want the chat
  • Load the Flow widget script dynamically
  • Call the mount function with your configuration
  • Widget renders inside your specified container
<!-- Container for the widget -->
<div id="chat-widget-container" style="height: 600px; width: 100%;"></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: 'optional-consumer-id',
    hmacSignature: 'optional-hmac-signature', 
    chatId: 'optional-chat-id',
    target: container
  });
};
document.head.appendChild(script);
</script>

Step 3: Handle Authentication (For Known Users)

Generate HMAC signatures server-side for authenticated user sessions.

  • Create a backend endpoint that generates HMAC signatures
  • Call this endpoint to get signatures for your users
  • Never generate HMAC signatures client-side
  • Use the signature in your widget configuration
// Example: Fetch HMAC signature and configure widget
fetch('/api/generateHmac', {
  method: 'POST',
  body: JSON.stringify({ consumerId: 'user_12345' }),
  headers: { 'Content-Type': 'application/json' }
})
.then(response => response.json())
.then(data => {
  // For Ping widget
  const script = document.createElement('script');
  script.src = 'https://unpkg.com/atri-ai-chat-widget-ping@latest/dist/bundle.js';
  script.setAttribute('data-project-id', 'your-project-id');
  script.setAttribute('data-consumer-id', 'user_12345');
  script.setAttribute('data-hmac-signature', data.hmacSignature);
  document.head.appendChild(script);
  
  // For Flow widget
  window.AtriChatFlow?.mount({
    projectId: 'your-project-id',
    consumerId: 'user_12345',
    hmacSignature: data.hmacSignature,
    target: document.getElementById('chat-container')
  });
});

Authentication Parameters Guide

Understanding when and how to use different authentication parameters:

Fresh Authenticated Chat

For logged-in users starting a new conversation

Parameters:consumerId + hmacSignature

Provide both parameters to create a new authenticated chat session

Resume Existing Chat

To continue a previous conversation

Parameters:chatId only

Use the specific chat ID to resume that conversation (consumer is auto-identified)

Anonymous Session

For guest users or temporary interactions

Parameters:projectId only

Only provide project ID - system creates temporary anonymous session using cookies

Template Customization Options

Ping Template Customization

Theme Color

Primary brand color for widget header and accents

Configure in your project dashboard under Template Settings

Header Text

Custom title displayed in chat widget header

Set in project dashboard Template Settings

Welcome Message

Initial greeting shown when users open the chat

Configure in project dashboard under Template Settings

Screen Position

Widget placement (bottom-right or bottom-left)

Select in project dashboard Template Settings

Flow Template Customization

Theme Color

Primary brand color for buttons and interface accents

Configure in your project dashboard under Template Settings

Title Text

Main application title at top of interface

Set in project dashboard Template Settings

Introductory Text

Welcome message shown when users first access chat

Configure in project dashboard under Template Settings

Security Best Practices

  • • Never expose your API key in client-side code
  • • Always generate HMAC signatures server-side using the /hmacSignature API endpoint
  • • Use HTTPS for all API calls and widget deployments
  • • Validate consumer IDs on your backend before generating HMAC signatures

Common Issues and Solutions

Widget not appearing

Check browser console for errors, verify project ID is correct, ensure script loads properly

Authentication errors

Verify HMAC signature is generated correctly server-side and consumer ID matches the signature

Styles not loading (React)

Ensure you've imported '@atri-ai/templates/styles.css' before using components

Flow widget container issues

Verify container element exists and has defined dimensions before mounting

Next Steps

After completing the integration, you can:

  • Customize your template appearance in the project dashboard
  • Use the /latestConsumerChatId API to resume previous conversations
  • Implement conversation management using chat IDs
  • Explore the full API reference for advanced features