Chatbot Integration

Integrate Ordify AI agents into your website or application using the Ordify Chat Widget. This professional, production-ready React component enables seamless AI chat functionality with zero configuration required.

Overview

The Ordify Chat Widget is a React component that connects your custom Ordify agents to any web application. It provides a polished, responsive chat interface that matches your brand and requires no CSS imports or complex setup. You can use it in a React app (npm) or on WordPress and other sites via a single script tag—no build step required.

Key Features

Zero Configuration: Drop-in chat widget with no CSS imports or additional setup
React or script-tag: Use from npm in a React app, or load via script tag on WordPress and static sites
Multiple Modes: Floating and embedded chat interfaces
Professional UI: Polished, responsive chat interface that matches your brand
Real-time AI: Direct integration with your Ordify AI agents for instant responses
TypeScript Support: Full type safety and IntelliSense
Customizable: Colors, themes, and styling options
Context Aware: Send hidden user context to AI for personalized responses
Welcome Screen: Display quick action questions before the session starts

Prerequisites

Before integrating the chat widget, ensure you have:

API Key: Available in your Ordify dashboard (Settings → API)
Agent ID: Found in your agent configuration panel within the Ordify application
React Application: Compatible with React 18+ and modern build tools

Quick Start

Step 1: Install the Library

npm install ordify-chat-widget

Step 2: Add to Your React App

import { OrdifyChat } from 'ordify-chat-widget'

function App() {
  return (
    <OrdifyChat
      agentId="your-agent-id"
      apiKey="your-api-key"
      apiBaseUrl="https://r.ordify.ai"
      chatName="AI Assistant"
      buttonText="?"
      initialContext="user_id: demo_user, page: /home"
    />
  )
}

That's it! No CSS imports, no additional setup. The library includes all necessary styles automatically.

Chat Modes

The widget supports three integration modes:

Floating Chat

A floating chat button that appears in the bottom-right corner of the page. Perfect for websites that want to provide chat support without taking up page space.

<OrdifyChat
  agentId="your-agent-id"
  apiKey="your-api-key"
  apiBaseUrl="https://r.ordify.ai"
  mode="floating"
  position="bottom-right"
  buttonText="AI Chat"
/>

Embedded Chat

A full-page chat interface embedded directly in your content. Ideal for dedicated support pages and documentation.

<OrdifyChat
  agentId="your-agent-id"
  apiKey="your-api-key"
  apiBaseUrl="https://r.ordify.ai"
  mode="embedded"
  height="500px"
  chatName="Support Assistant"
/>

Inline Chat

A compact chat widget that fits seamlessly inline with your content. Great for product pages and FAQ sections.

<OrdifyChat
  agentId="your-agent-id"
  apiKey="your-api-key"
  apiBaseUrl="https://r.ordify.ai"
  mode="embedded"
  height="300px"
  chatName="Product Assistant"
/>

Configuration Options

Required Props

agentId (string): Your Ordify agent ID
apiKey (string): Your API key

Optional Props

Option	Type	Default	Description
`apiBaseUrl`	string	`"https://r.ordify.ai"`	API endpoint URL
`chatName`	string	`"Chat Assistant"`	Title text in chat header
`buttonText`	string	`"AI Chat"`	Text on floating button
`mode`	string	`"floating"`	Chat display mode: `"floating"` or `"embedded"`
`position`	string	`"bottom-right"`	Floating button position
`primaryColor`	string	-	Custom primary color for welcome screen gradient and header
`agentImage`	string	-	URL to agent avatar image (shown in header and next to assistant messages)
`onSessionCreated`	function	-	Callback function called when a new session is created with the session ID
`initialMessage`	string	-	Optional message to automatically send when the chat widget loads
`initialContext`	string	-	Optional hidden context sent to AI (user ID, page info, analytics) - never displayed to users
`quickQuestions`	string[]	-	Optional array of quick action questions displayed as buttons in welcome screen
`welcomeMessage`	string	`"Hi there 👋 How can we help?"`	Custom greeting message shown in welcome screen when quickQuestions are provided
`welcomeImage`	string	-	Optional URL to image/graphic displayed in welcome screen
`theme`	string	`"auto"`	Force theme: `"light"`, `"dark"`, or `"auto"` (follow system preference)

WordPress Integration

You can add the chat widget to WordPress (or any site without React) by loading the standalone script from a CDN and calling the global mount API. No npm or React required.

Option 1: Theme (e.g. Twenty Twenty-Five)

Add the script and config in your theme’s functions.php. The widget will load on every front-end page.

// In your theme's functions.php
if ( ! function_exists( 'your_theme_ordify_chat_widget' ) ) :
	function your_theme_ordify_chat_widget() {
		if ( is_admin() ) {
			return;
		}
		$config = array(
			'agentId'         => 'your-agent-id',
			'apiKey'          => 'your-api-key',
			'apiBaseUrl'      => 'https://r.ordify.ai',
			'mode'            => 'floating',
			'position'        => 'bottom-right',
			'buttonText'      => 'Chat',
			'chatName'        => 'Assistant',
			'primaryColor'    => '#f3b43b',
			'agentImage'      => 'https://example.com/agent-avatar.jpg',
			'welcomeMessage'  => 'Hi, how can we help?',
			'quickQuestions'  => array(
				'Where is your location?',
				'How do I schedule an appointment?',
			),
		);
		$script_url = 'https://unpkg.com/ordify-chat-widget/dist/ordify-chat-widget.standalone.js';
		?>
		<script src="<?php echo esc_url( $script_url ); ?>"></script>
		<script>OrdifyChatWidget.mount(null, <?php echo wp_json_encode( $config ); ?>);</script>
		<?php
	}
endif;
add_action( 'wp_footer', 'your_theme_ordify_chat_widget', 99 );

Replace your-agent-id and your-api-key with your Ordify credentials. Use a pinned version in the script URL (e.g. @1.0.42) so updates are intentional; check npm for the latest version.

Option 2: Plugin (Insert Headers and Footers, WPCode, etc.)

Paste the same script and config in a header/footer or custom-code plugin. Use the HTML version:

<script src="https://unpkg.com/ordify-chat-widget@1.0.42/dist/ordify-chat-widget.standalone.js"></script>
<script>
  OrdifyChatWidget.mount(null, {
    agentId: "your-agent-id",
    apiKey: "your-api-key",
    apiBaseUrl: "https://r.ordify.ai",
    mode: "floating",
    position: "bottom-right",
    buttonText: "Chat",
    chatName: "Assistant",
    theme: "light",
    primaryColor: "#f3b43b",
    welcomeMessage: "Hi, how can we help?",
    quickQuestions: [
      "Do you take Insurance?",
      "How much do hearing aids cost?",
      "Where is your location?",
      "How do I schedule an appointment?"
    ]
  });
</script>

Option 3: Data attributes (one script tag)

Add a single script tag with data-ordify-widget and data attributes. The widget auto-mounts when the script loads.

<script
  src="https://unpkg.com/ordify-chat-widget@1.0.42/dist/ordify-chat-widget.standalone.js"
  data-ordify-widget
  data-ordify-agent-id="your-agent-id"
  data-ordify-api-key="your-api-key"
  data-ordify-api-base-url="https://r.ordify.ai"
  data-ordify-theme="light"
  data-ordify-button-text="Chat"
  data-ordify-chat-name="Assistant"
  data-ordify-quick-questions='["Do you take Insurance?","How much do hearing aids cost?"]'
></script>

WordPress notes

Credentials: Store your API key and Agent ID in the same place as the script (theme, plugin, or database via a plugin). The widget does not use a separate config file.
Best practice: Prefer a header/footer or code-snippet plugin so credentials and snippet live in the database and survive theme updates. Avoid putting secrets only in theme files if you update themes often.
Theme option: Set theme to "light" or "dark" to force the widget appearance; use "auto" (default) to follow the user’s system preference.

Integration Examples

Next.js App Router

// app/chat/page.tsx
'use client'

import { OrdifyChat } from 'ordify-chat-widget'

export default function ChatPage() {
  return (
    <div className="container mx-auto p-4">
      <h1 className="text-2xl font-bold mb-4">Chat with AI</h1>
      <OrdifyChat 
        agentId={process.env.NEXT_PUBLIC_ORDIFY_AGENT_ID!}
        apiKey={process.env.NEXT_PUBLIC_ORDIFY_API_KEY!}
        apiBaseUrl="https://r.ordify.ai"
        mode="embedded"
        height="500px"
      />
    </div>
  )
}

React Component

// components/ChatWidget.tsx
import { OrdifyChat } from 'ordify-chat-widget'

export function ChatWidget() {
  return (
    <OrdifyChat
      agentId="your-agent-id"
      apiKey="your-api-key"
      apiBaseUrl="https://r.ordify.ai"
      mode="floating"
      position="bottom-right"
      buttonText="?"
    />
  )
}

Session Management

Access and track session IDs for user management and analytics:

import { useState } from 'react'
import { OrdifyChat } from 'ordify-chat-widget'

export function ChatWithSessionTracking() {
  const [sessionId, setSessionId] = useState<string | null>(null)

  return (
    <div>
      {sessionId && (
        <div className="mb-4 p-3 bg-blue-50 border border-blue-200 rounded-lg">
          <p className="text-sm text-blue-800">
            <strong>Session ID:</strong> <code className="bg-blue-100 px-2 py-1 rounded text-xs">{sessionId}</code>
          </p>
        </div>
      )}
      
      <OrdifyChat
        agentId="your-agent-id"
        apiKey="your-api-key"
        apiBaseUrl="https://r.ordify.ai"
        mode="floating"
        onSessionCreated={(id) => {
          setSessionId(id)
          console.log('New session created:', id)
          // Store in localStorage, send to analytics, etc.
        }}
      />
    </div>
  )
}

Hidden Context Feature

Send important user information to your AI agent without displaying it to users. Perfect for user identification, page context, analytics, and personalized responses.

What Gets Sent

User ID and email
Current page URL
Subscription tier
Cart items count
Campaign source
Custom analytics data

What Users See

Only the initial message
Normal chat conversation
No context data visible
Clean, user-friendly interface

Example Usage

import { OrdifyChat } from 'ordify-chat-widget'
import { useUser } from './hooks/useUser'
import { useRouter } from 'next/router'

export function ChatWithContext() {
  const { user } = useUser()
  const router = useRouter()

  return (
    <OrdifyChat
      agentId="your-agent-id"
      apiKey="your-api-key"
      apiBaseUrl="https://r.ordify.ai"
      mode="floating"
      buttonText="?"
      initialMessage={`Hi! I'm ${user?.name || 'a visitor'}, help me with this page.`}
      initialContext={`user_id: ${user?.id}, email: ${user?.email}, page: ${router.pathname}, tier: ${user?.subscriptionTier || 'free'}`}
      onSessionCreated={(sessionId) => {
        console.log('Session created with context:', sessionId)
        // Analytics tracking with user context
        analytics.track('chat_session_started', {
          sessionId,
          userId: user?.id,
          page: router.pathname
        })
      }}
    />
  )
}

Key Benefits: Send user ID, page URL, subscription tier, cart items, or any analytics data to your AI agent. This context helps provide personalized responses while keeping the user interface clean.

Welcome Screen with Quick Questions

Display a welcome screen with quick action questions before the session starts. Users can either click a quick question button or type their own custom message to start the chat.

import { OrdifyChat } from 'ordify-chat-widget'

export function ChatWithQuickQuestions() {
  return (
    <OrdifyChat
      agentId="your-agent-id"
      apiKey="your-api-key"
      apiBaseUrl="https://r.ordify.ai"
      mode="floating"
      buttonText="?"
      chatName="Support Assistant"
      agentImage="https://example.com/agent-avatar.png"
      quickQuestions={[
        "I want to schedule an appointment.",
        "I want to find a location near me.",
        "I want a FREE hearing screening.",
        "I have a question about something else.",
        "Please contact me."
      ]}
      welcomeMessage="Hi there 👋 How can we help?"
      welcomeImage="https://example.com/welcome-graphic.png"
      onSessionCreated={(sessionId) => {
        console.log('Session started:', sessionId)
      }}
    />
  )
}

Key Features: Users can either click a quick question button or type their own custom message to start the chat. The welcome screen displays before the session starts, providing a guided experience while maintaining flexibility.

Landing Page Integration

Add chat support to your marketing pages:

// pages/index.tsx
import { OrdifyChat } from 'ordify-chat-widget'

export default function HomePage() {
  return (
    <div>
      {/* Your existing page content */}
      <h1>Welcome to Our Site</h1>
      <p>Content here...</p>
      
      {/* Add chat widget */}
      <OrdifyChat
        agentId="your-agent-id"
        apiKey="your-api-key"
        apiBaseUrl="https://r.ordify.ai"
        mode="floating"
        buttonText="?"
      />
    </div>
  )
}

Resources

Live Demo:** Test the chat widget with your own credentials without any coding at https://app.ordify.ai/widget-demo
GitHub Repository:** View the source code, report issues, and contribute at https://github.com/Ordify-Ai/chat-widget
Full Documentation:** For complete API reference and advanced usage, visit https://app.ordify.ai/docs/chat-widget-integration

Overview​

Key Features​

Prerequisites​

Quick Start​

Step 1: Install the Library​

Step 2: Add to Your React App​

Chat Modes​

Floating Chat​

Embedded Chat​

Inline Chat​

Configuration Options​

Required Props​

Optional Props​

WordPress Integration​

Option 1: Theme (e.g. Twenty Twenty-Five)​

Option 2: Plugin (Insert Headers and Footers, WPCode, etc.)​

Option 3: Data attributes (one script tag)​

WordPress notes​

Integration Examples​

Next.js App Router​

React Component​

Session Management​

Hidden Context Feature​

What Gets Sent​

What Users See​

Example Usage​

Welcome Screen with Quick Questions​

Landing Page Integration​

Resources​