Widget
Widget embed & config
The Talki widget is a lightweight JavaScript snippet that adds a live chat button to any website. It works on plain HTML, React, Next.js, Webflow, Shopify, and any other platform that allows custom JavaScript.
Installation
Add the following before the closing </body> tag of every page where you want the widget to appear.
<!-- Talki Widget — place before </body> -->
<script>
window.TalkiConfig = {
orgId: 'YOUR_ORG_ID', // required
apiKey: 'YOUR_API_KEY', // required
primaryColor: '#2ec882', // optional
position: 'bottom-right', // optional
theme: 'auto', // optional
welcomeMessage: 'Hi! How can we help?', // optional
hideButton: false, // optional
};
</script>
<script src="https://cdn.talki.tech/widget.js" async></script>Next.js / App Router
Use next/script in your root layout for proper SSR-safe loading.
// app/layout.tsx
import Script from 'next/script';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
{children}
<Script id="talki-config" strategy="beforeInteractive">
{`window.TalkiConfig = {
orgId: '${process.env.NEXT_PUBLIC_TALKI_ORG_ID}',
apiKey: '${process.env.NEXT_PUBLIC_TALKI_API_KEY}',
};`}
</Script>
<Script
src="https://cdn.talki.tech/widget.js"
strategy="lazyOnload"
/>
</body>
</html>
);
}ⓘEnvironment variables
.env.local as NEXT_PUBLIC_TALKI_ORG_ID and NEXT_PUBLIC_TALKI_API_KEY. Never commit real secrets to source control.Configuration reference
All options are set via window.TalkiConfig before the script loads.
| Name | Type | Description |
|---|---|---|
| orgId | string | Your Talki Organization ID. Found in Admin → API Keys. |
| apiKey | string | Your public API key. Safe to expose in frontend code — scoped to widget operations only. |
| primaryColor | string | Accent color for the widget header and buttons. Accepts any CSS color value (hex, hsl, rgb). |
| position | "bottom-right" | "bottom-left" | Corner of the screen where the chat button appears. |
| theme | "auto" | "light" | "dark" | "auto" follows the OS preference. Override with "light" or "dark" to force a specific theme. |
| welcomeMessage | string | First message shown inside the widget before the user sends anything. Supports plain text. |
| hideButton | boolean | Set to true to hide the floating bubble. Use window.Talki.open() to show the widget on your own trigger. |
| identity | object | Pre-fills the user's identity so operators see who's writing. See Identity section below. |
| locale | string | BCP-47 locale tag (e.g. "fr", "de", "es") to force a specific language in the widget UI. |
User identity
Pass the logged-in user's data so operators see who's writing without asking for it. Identity fields are shown in the ticket panel and used by Backend Connect to resolve customer data.
window.TalkiConfig = {
orgId: 'YOUR_ORG_ID',
apiKey: 'YOUR_API_KEY',
identity: {
userId: 'usr_abc123', // your internal user ID
name: 'Alice Johnson',
email: 'alice@example.com',
},
};| Name | Type | Description |
|---|---|---|
| userId | string | Your application's user ID. Passed to Backend Connect as the visitorId. |
| name | string | Display name shown to operators in the ticket. |
| string | User's email address. Pre-fills the email field and shown in the ticket panel. |
Programmatic control
After the widget loads, window.Talki exposes a small imperative API for opening, closing, and inspecting the widget.
// Programmatically open the widget
window.Talki?.open();
// Open with a pre-filled message
window.Talki?.open({ message: 'I need help with my order' });
// Close the widget
window.Talki?.close();
// Check if widget is open
const isOpen = window.Talki?.isOpen();✦Open on custom trigger
hideButton: true in your config and call window.Talki.open() from a button click to use your own UI element instead of the default bubble.