@expeai/react
v0.1.1
Published
React/Next.js integration for Expe chat widget
Maintainers
raphaelcostaReadme
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/reactQuick 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_SECRETsecure 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