@expeai/react NPM

Expe React

A powerful React integration for the Expe chat widget, featuring first-class support for Next.js and modern React applications.

Features

🚀 First-class Next.js App Router support
💪 Full TypeScript support
🔒 Secure authentication handling
🎨 Customizable UI and theming
🔌 Framework-agnostic core
📱 Responsive design

Installation

npm install @expeai/react
# or
yarn add @expeai/react
# or
pnpm add @expeai/react

Quick Start

Add your Expe credentials to .env.local:

EXPE_HMAC_SECRET=your_secret_from_expe_dashboard
EXPE_MAILBOX_SLUG=your_mailbox_slug

Use in your application (Next.js example):

// app/layout.tsx
import { generateExpeAuth, ExpeProvider } from "@expeai/react";

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const session = await auth(); // Your auth solution
  if (!session?.user?.email) return children;

  const expeAuth = await generateExpeAuth({
    email: session.user.email,
  });

  const config = {
    ...expeAuth,
    title: "Support",
  };

  return (
    <html>
      <body>
        <ExpeProvider {...config}>{children}</ExpeProvider>
      </body>
    </html>
  );
}

For other frameworks, ensure authentication is always generated server-side:

// pages/api/expe-auth.ts
import { generateExpeAuth } from "@expeai/react/server";

export default async function handler(req, res) {
  const session = await getSession(req); // Your auth solution
  if (!session?.user?.email) {
    return res.status(401).json({ error: "Unauthorized" });
  }

  const expeAuth = await generateExpeAuth({
    email: session.user.email,
  });

  res.json(expeAuth);
}

Anonymous Sessions

Expe also supports anonymous sessions that don't require user authentication. Here's how to implement them:

// app/public-chat.tsx
import { ExpeProvider } from "@expeai/react";

export default async function PublicChat() {
  const config = {
    mailbox_slug: process.env.EXPE_MAILBOX_SLUG,
    title: "Public Support Chat",
  };

  return (
    <div>
      <h1>Public Support Chat</h1>
      <ExpeProvider {...config}>
        <ChatContent />
      </ExpeProvider>
    </div>
  );
}

For API routes:

// pages/api/public-expe-auth.ts
export default async function handler(req, res) {
  res.json({
    mailbox_slug: process.env.EXPE_MAILBOX_SLUG,
  });
}

Configuration

Session Types

Expe supports two types of sessions:

Authenticated Sessions

Require user email and generate secure HMAC authentication:

const config = await generateExpeAuth({
  email: user.email,
  // Optional: provide HMAC secret directly instead of using env var
  hmacSecret: "your_secret",
  // Optional: provide mailbox slug directly instead of using env var
  mailboxSlug: "your_mailbox",
});

Anonymous Sessions

Only require a mailbox slug, no authentication needed:

const config = {
  mailbox_slug: "your_mailbox",
  title: "Support Chat", // optional
};

Note: Anonymous sessions have limited functionality:

No conversation history
No user-specific features
Messages are not associated with an email address

Customer Metadata Examples

Below are common patterns for different use cases:

// SaaS Application
const metadata = {
  name: user.displayName,
  value: user.lifetimeValue, // Total value from all subscriptions
  links: {
    "User Profile": `/users/${user.id}`,
    "Billing History": `/users/${user.id}/billing`,
    "Support Tickets": `/users/${user.id}/tickets`,
  },
};

// E-commerce Platform
const metadata = {
  name: customer.name,
  value: customer.totalSpent, // Total spent across all orders
  links: {
    "Customer Profile": `/customers/${customer.id}`,
    "Order History": `/customers/${customer.id}/orders`,
    "Return Requests": `/customers/${customer.id}/returns`,
  },
};

Best Practices

Security

Keep EXPE_HMAC_SECRET secure and never expose it client-side
Generate authentication tokens server-side
Validate user sessions before initializing Expe
Use environment variables for sensitive configuration

Performance

Initialize Expe only after user authentication
Implement proper cache invalidation strategies
Use framework-specific optimizations when available

API Reference

Hooks

`useExpe()`

const {
  show, // () => void
  hide, // () => void
  toggle, // () => void
  sendPrompt, // (prompt: string) => void
  isVisible, // boolean
} = useExpe();

Components

`ExpeProvider`

<ExpeProvider
  {...authConfig}
>
  {children}
</ExpeProvider>

Troubleshooting

Common Issues

Widget Not Loading

Verify environment variables are correctly set
Ensure HMAC generation is working
Check network requests for authentication errors

Authentication Failures

Confirm HMAC secret matches dashboard
Verify timestamp is current
Validate email format and consistency

License

MIT © Expe

expe chat ai widget sdk react nextjs customer-service

crypto-js

0.1.1

9 months ago

0.1.0

9 months ago