Skip to content

Commit 4f05d89

Browse files
oliwiapolecoliwiapolec
authored
feat(docs): Add Custom Chat Widgets guide
1 parent 7e73f83 commit 4f05d89

File tree

8 files changed

+304
-44
lines changed

8 files changed

+304
-44
lines changed

‎src/components/Page/index.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ import Rating from "../core/Rating";
2525
import Footer from "../core/Footer/Footer";
2626
import {
2727
Headings,
28+
Sections,
2829
CodeBlocks,
2930
Scopes,
3031
Errors,
@@ -50,6 +51,7 @@ const ContentSideNav = dynamic(
5051
const components = {
5152
...CodeBlocks,
5253
...Headings,
54+
...Sections,
5355
Scopes,
5456
Errors,
5557
Placeholder,

‎src/components/extensions/Headings.js‎

Lines changed: 0 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -133,41 +133,6 @@ const BannerImage = ({ to }) => {
133133
}
134134
};
135135

136-
const StyledLink = styled.a`
137-
font-weight: 600;
138-
cursor: pointer;
139-
140-
&:after {
141-
content: "";
142-
width: 16px;
143-
height: 16px;
144-
display: inline-block;
145-
vertical-align: middle;
146-
margin-bottom: 1px;
147-
background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 24 24'%3E%3Cpath d='M10 6L8.59 7.41 13.17 12l-4.58 4.59L10 18l6-6z' fill='%232200ff'/%3E%3Cpath d='M0 0h24v24H0z' fill='none'/%3E%3C/svg%3E");
148-
}
149-
`;
150-
151-
const SectionLink = ({ to, href, children, ...rest }) => {
152-
if (href) {
153-
return (
154-
<Link href={href} target="_blank" {...rest}>
155-
<StyledLink>{children}</StyledLink>
156-
</Link>
157-
);
158-
}
159-
160-
if (to) {
161-
return (
162-
<Link href={to} {...rest}>
163-
<StyledLink>{children}</StyledLink>
164-
</Link>
165-
);
166-
}
167-
168-
return <StyledLink>{children}</StyledLink>;
169-
};
170-
171136
const makeHeading = (size) => ({ children, ...props }) => {
172137
const className = "heading";
173138

@@ -234,7 +199,6 @@ export default {
234199
img: Image,
235200
pre: Pre,
236201
Warning,
237-
SectionLink,
238202
table: ({ children }) => (
239203
<TableWrapper>
240204
<table>{children}</table>

‎src/components/extensions/Sections.js‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
import React from "react";
2+
/** @jsx jsx */
3+
import { jsx, css } from "@emotion/core";
4+
import styled from "@emotion/styled";
5+
import PropTypes from "prop-types";
6+
7+
import Link from "next/link";
8+
9+
const StyledLink = styled.a`
10+
font-weight: 600;
11+
cursor: pointer;
12+
13+
&:after {
14+
content: "";
15+
width: 16px;
16+
height: 16px;
17+
display: inline-block;
18+
vertical-align: middle;
19+
margin-bottom: 1px;
20+
background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 24 24'%3E%3Cpath d='M10 6L8.59 7.41 13.17 12l-4.58 4.59L10 18l6-6z' fill='%232200ff'/%3E%3Cpath d='M0 0h24v24H0z' fill='none'/%3E%3C/svg%3E");
21+
}
22+
`;
23+
24+
const SmallStyledLink = styled(StyledLink)`
25+
font-size: 14px;
26+
`;
27+
28+
const SmallLinksSectionWrapper = styled.div`
29+
display: flex;
30+
flex-direction: column;
31+
margin-bottom: 24px;
32+
`;
33+
34+
const SmallLinksSectionHeader = styled.div`
35+
font-size: 12px;
36+
font-weight: 600;
37+
text-transform: uppercase;
38+
letter-spacing: 0.4px;
39+
color: #5e6c78;
40+
margin-bottom: 2px;
41+
`;
42+
43+
const SmallLinksList = styled.div`
44+
display: flex;
45+
flex-direction: column;
46+
`;
47+
48+
const SectionLink = ({ to, href, children, ...rest }) => {
49+
if (href) {
50+
return (
51+
<Link href={href} target="_blank" {...rest}>
52+
<StyledLink>{children}</StyledLink>
53+
</Link>
54+
);
55+
}
56+
57+
if (to) {
58+
return (
59+
<Link href={to} {...rest}>
60+
<StyledLink>{children}</StyledLink>
61+
</Link>
62+
);
63+
}
64+
65+
return <StyledLink>{children}</StyledLink>;
66+
};
67+
68+
SectionLink.propTypes = {
69+
to: PropTypes.string,
70+
href: PropTypes.string,
71+
children: PropTypes.node.isRequired,
72+
};
73+
74+
const SmallLinksSection = ({ header, links = [] }) => {
75+
const renderLink = ({ to, href, children, ...rest }, index) => {
76+
const url = href ?? to;
77+
const styled = <SmallStyledLink>{children}</SmallStyledLink>;
78+
79+
return url ? (
80+
<Link
81+
key={index}
82+
href={url}
83+
{...rest}
84+
{...(href ? { target: "_blank" } : {})}
85+
>
86+
{styled}
87+
</Link>
88+
) : (
89+
<SmallStyledLink key={index} {...rest}>
90+
{children}
91+
</SmallStyledLink>
92+
);
93+
};
94+
95+
return (
96+
<SmallLinksSectionWrapper>
97+
{header && <SmallLinksSectionHeader>{header}</SmallLinksSectionHeader>}
98+
<SmallLinksList>{links.map(renderLink)}</SmallLinksList>
99+
</SmallLinksSectionWrapper>
100+
);
101+
};
102+
103+
SmallLinksSection.propTypes = {
104+
header: PropTypes.string,
105+
links: PropTypes.arrayOf(
106+
PropTypes.shape({
107+
to: PropTypes.string,
108+
href: PropTypes.string,
109+
children: PropTypes.node.isRequired,
110+
})
111+
),
112+
};
113+
114+
export default {
115+
SectionLink,
116+
SmallLinksSection,
117+
};

‎src/components/extensions/index.js‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
import Headings from "./Headings";
2+
import Sections from "./Sections";
23
import * as CodeBlocks from "./CodeBlocks";
34
import Scopes from "./Scopes";
45
import Errors from "./Errors";
56
import Placeholder from "./Placeholder";
6-
import Image from "./Image"
7+
import Image from "./Image";
78

8-
export { Headings, CodeBlocks, Scopes, Errors, Placeholder, Image };
9+
export { Headings, CodeBlocks, Sections, Scopes, Errors, Placeholder, Image };

‎src/configs/containers.json‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -157,19 +157,23 @@
157157
},
158158
{
159159
"slug": "/guides/livechat-apps",
160-
"title": "LiveChat Apps"
160+
"title": "LiveChat apps"
161161
},
162162
{
163163
"slug": "/guides/helpdesk-apps",
164-
"title": "HelpDesk Apps"
164+
"title": "HelpDesk apps"
165+
},
166+
{
167+
"slug": "/guides/custom-chat-widgets",
168+
"title": "Custom chat widgets"
165169
},
166170
{
167171
"slug": "/guides/api-guides",
168-
"title": "API Guides"
172+
"title": "API guides"
169173
},
170174
{
171175
"slug": "/guides/console-guides",
172-
"title": "Console Guides"
176+
"title": "Console guides"
173177
},
174178
{
175179
"slug": "/guides/mcp",

‎src/pages/guides/custom-chat-widgets/index.mdx‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
---
2+
weight: 13
3+
category: "guides"
4+
subcategory: "custom-chat-widgets"
5+
title: "Custom chat widgets with Customer Chat API"
6+
tagline: "Learn how to approach building a custom chat widget with the Customer Chat API."
7+
desc: "Read a technical overview and business considerations for building custom chat widgets with the Customer Chat API."
8+
---
9+
10+
## What are custom chat widgets?
11+
12+
The [LiveChat Customer Chat API](https://platform.text.com/docs/messaging/customer-chat-api) lets you build custom chat widgets that are completely embedded in your website, mobile app, or any other digital touchpoint. Unlike the [standard LiveChat widget](https://www.livechat.com/features/customization/), which appears similar across implementations, custom widgets built with the Customer Chat API give you full control over design, behavior, and integration, while leveraging our messaging infrastructure.
13+
14+
**How it works:** When customers interact with your custom widget, the Customer Chat API processes their messages and routes them to your LiveChat app, where your agents respond. Your customers see your branded interface. Your agents use the full LiveChat platform they're familiar with.
15+
16+
**The distinction:**
17+
18+
**A standard LiveChat widget** gives you a pre-built interface with basic customization options (colors, position, text).
19+
20+
**A custom widget built with the Customer Chat API** provides a fully customized interface that you build to your exact specifications, integrated directly into your digital experience.
21+
22+
Think of it as the difference between using a template website builder versus hiring a designer to create exactly what your business needs.
23+
24+
## When to build custom chat widgets?
25+
26+
Custom widgets solve specific problems that the standard widget can't always address. Consider custom implementation when you have one or more of these requirements:
27+
28+
### Complete brand control and differentiated UX
29+
30+
Companies in competitive markets face a challenge. In luxury ecommerce, premium SaaS, and financial services, a generic chat widget creates visual discontinuity. This can undermine the trust you've built through your brand. Custom widgets eliminate this friction by maintaining seamless brand consistency.
31+
32+
Research shows that consistent branding across all customer touchpoints can increase revenue by [up to 23%](https://exclaimer.com/blog/brand-consistency-supercharging-trust/). What's more, [67% of customers](https://www.edelman.com/sites/g/files/aatuss191/files/2019-06/2019_edelman_trust_barometer_special_report_in_brands_we_trust.pdf) believe trust is essential before they'll buy from a brand.
33+
34+
**This matters most for:**
35+
36+
* Premium brands where visual identity drives purchase decisions
37+
* Companies with strong brand guidelines that must be maintained everywhere
38+
* Businesses competing primarily on customer experience quality
39+
40+
### Deep system integration
41+
42+
Generic widgets don't have direct access your proprietary systems. With the Customer Chat API, you can display any customer account information within the chat interface, perform actions specific to your product features, and pull data from any database to personalize each conversation.
43+
44+
Integrations like these eliminate the inefficiency of agents switching between systems. Unlike phone calls, where agents handle one at a time, agents can handle multiple concurrent chat conversations. System integration amplifies this efficiency.
45+
46+
**This matters most for:**
47+
48+
* Ecommerce companies wanting to instantly display order status in chat
49+
* SaaS businesses needing to access customer usage data
50+
* Financial services requiring secure account information display
51+
* Any business with critical customer data in proprietary systems
52+
53+
### Advanced personalization and behavioral targeting
54+
55+
Standard widgets offer basic triggers, such as time on page or exit intent. Custom widgets let you trigger conversations based on advanced, proprietary data, including cart value thresholds, customer lifecycle stages, product complexity indicators, or risk signals, such as repeated failed actions in your app.
56+
57+
[Research shows](https://www.livechat.com/success/live-chat-conversion-rate-optimization/) that customers who engage with chat are 2.8 times more likely to convert than those who don't, and chat-engaged customers spend 60% more per purchase on average. Intelligent targeting maximizes these benefits by engaging the right customers at the right moments.
58+
59+
**This matters most for:**
60+
61+
* Ecommerce with sophisticated segmentation strategies
62+
* SaaS companies with complex onboarding journeys
63+
* High-consideration purchases (B2B, real estate, financial products)
64+
* Any business with detailed customer behavior data
65+
66+
### Native mobile app integration
67+
68+
[Over 50% of live chat interactions](https://www.livechat.com/success/live-chat-conversion-rate-optimization/) occur on mobile devices. Web widgets embedded in mobile apps often create poor user experiences — they don't feel native, can't access device features, and don't support platform conventions.
69+
70+
The Customer Chat API lets you build native mobile chat experiences that integrate with device cameras, support push notifications, and follow your product design.
71+
72+
**This matters most for:**
73+
74+
* Mobile banking apps where chat is a primary support channel
75+
* Delivery and logistics apps requiring real-time support
76+
* Retail apps where mobile drives a significant percentage of transactions
77+
* Any business with high mobile app engagement
78+
79+
### Industry-specific compliance or features
80+
81+
Regulated industries often can't use standard widgets due to security, data handling, or audit requirements. The Customer Chat API gives you more control over the customer data you send through the API and lets you manage authentication and authorization systems.
82+
83+
**This matters most for:**
84+
85+
* Healthcare providers requiring HIPAA compliance
86+
* Financial institutions with PCI-DSS requirements
87+
* Legal services handling privileged communications
88+
* Any business operating under strict regulatory frameworks
89+
90+
## Who are custom widgets for?
91+
92+
The decision to build a custom widget isn't about budget alone — it's about strategic fit. Custom development makes sense when the standard widget creates meaningful gaps in your customer experience, brand presentation, or operational capabilities.
93+
94+
### Ideal candidates for custom widgets
95+
96+
* You have **development resources** and a **budget** available
97+
* You use live chat **strategically for customer experience**, not just as a support channel
98+
* You need **consistent brand presentation** across all customer touchpoints
99+
* You need to **integrate with proprietary systems** or databases
100+
* You operate in a regulated industry with specific **compliance requirements**
101+
* You have **high-value transactions** where small conversion improvements equal big revenue impact
102+
* Your **mobile app users** comprise a significant percentage of customers
103+
104+
### When the standard widget is the better choice
105+
106+
The standard widget delivers the core benefits of live chat — a [20% increase](https://www.livechat.com/success/live-chat-conversion-rate-optimization/) in conversions, [2.8 times higher](https://www.livechat.com/success/live-chat-conversion-rate-optimization/) conversion rates for chat users, and a [60% increase](https://www.livechat.com/success/live-chat-conversion-rate-optimization/) in spending per chat-engaged customer. For many businesses, this alone is sufficient and works great for their use cases.
107+
108+
The standard widget will be a good choice for you when you're still testing whether chat drives business value, your budget, time-to-market, or development resources are low, or when basic branding customization meets your needs.
109+
110+
## Pros and cons of building a custom chat widget
111+
112+
| Consideration | Custom widget | Standard LiveChat widget |
113+
| ------------------------ | --------------------------------------------------- | ------------------------------------------------------ |
114+
| **Brand consistency** | ✅ Complete control over every visual element | ⚠️ Limited to color, position, and text customization |
115+
| **Development cost** | ❌ Depending on complexity | ✅ Included with LiveChat subscription |
116+
| **Time to deploy** | ❌ Longer for complex builds | ✅ 15 minutes to install |
117+
| **System integration** | ✅ Deep API integration with any system | ⚠️ Limited to available product features |
118+
| **Mobile experience** | ✅ Native mobile apps with full platform integration | ⚠️ Web widget embedded in mobile view |
119+
| **Behavioral targeting** | ✅ Any trigger based on your business logic and data | ⚠️ Basic triggers (time on page, exit intent) |
120+
| **Compliance** | ✅ More control over data and security | ⚠️ Limited by standard implementation |
121+
| **Maintenance** | ❌ Ongoing development required | ✅ Maintained by LiveChat |
122+
| **Technical expertise** | ❌ Requires developers familiar with APIs | ✅ No technical knowledge required |
123+
| **Agent experience** | ✅ Agents use the native app | ✅ Agents use the native app |
124+
| **Flexibility** | ✅ Can adapt to any business requirement | ⚠️ Limited to available configuration options |
125+
| **Support** | ⚠️ You're responsible for your custom code | ✅ Full LiveChat support for the widget functionalities |
126+
127+
## Implementation outline
128+
129+
A stateful implementation uses WebSocket technology — the same real-time communication standard that powers Slack, WhatsApp, and most modern messaging applications.
130+
131+
The pattern is straightforward:
132+
133+
1. **Authenticate** using OAuth 2.0 (industry standard).
134+
2. **Open a WebSocket connection** to maintain real-time communication.
135+
3. **Exchange messages as JSON events** through that connection.
136+
4. **Customize product-specific behavior and widget design** to your implementation needs.
137+
138+
The API handles all the complex backend operations — message persistence, agent routing, and chat management. Your development team focuses on the customer-facing interface and experience.
139+
140+
For teams experienced with modern web development, this is a well-understood implementation pattern. The effort scales based on the complexity of your design and custom features.
141+
142+
### Passing custom information
143+
144+
Sending custom customer information to your agents is essential for customizing your widget flow. Custom widgets send this information through two mechanisms:
145+
146+
* [Properties](/messaging/customer-chat-api#properties): Properties store persistent business context (account tier, purchase history, and support status) that remains valuable across all conversations with that customer. Think of properties as "who's this person to our business?"
147+
* [Session fields](/messaging/customer-chat-api#update-customer): Session fields track temporary browsing behavior (pages viewed, time on site, and current cart value) that's relevant only during the active visit. Think of session fields as "what's this person doing right now?"
148+
149+
Both appear in your agents' LiveChat app to help provide context and personalize conversations.
150+
151+
## Next steps
152+
153+
1. <SectionLink to={"/messaging/customer-chat-api"}>Review the Customer Chat API documentation</SectionLink>
154+
2. <SectionLink to={"/getting-started"}>Get to know the API usage details</SectionLink>
155+
3. **[Test with the standard widget first ›](https://www.livechat.com/signup/)**
156+
4. **[Discuss your specific use case and implementation options with our team ›](mailto:[email protected])**

‎src/pages/messaging/customer-chat-api/index.mdx‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,15 @@ robots: "noindex"
1111

1212
import { openChatWindow } from "utils/index";
1313

14-
# Introduction
14+
<SmallLinksSection
15+
header="Related guides"
16+
links={[
17+
{ to: "/guides/api-guides/customer-chat-api-guide", children: "Customer Chat API implementation guide" },
18+
{ to: "/guides/custom-chat-widgets/", children: "Custom chat widgets with Customer Chat API" },
19+
]}
20+
/>
21+
22+
---
1523

1624
## Versioning
1725

0 commit comments

Comments
 (0)