Add customer support chat to Next.js.
Give people a place to ask for help inside your web app. Install Macaron’s website widget in an App Router layout, reply from your inbox and keep reproducible bugs attached to a fix report.
Add your website freeBy Macaron · Updated
1. Create your website workspace
In Macaron, choose Apps → Add app → Website. Enter your name and published HTTPS website address, review and create it. Open Set up chat, enable customer chat and choose Next.js. Copy the code with your actual app ID already filled in.
You need access to your Next.js project and its deployment. You do not need to connect a model, payment provider or repository to send and receive chat messages. A website URL alone does not install the widget.
2. Add the script to your shared layout
First add your website in Macaron, open Set up chat and enable customer chat. Choose Next.js to get the snippet with your product’s public app ID already filled in. Adding a URL alone does not install the widget or send visitor messages.
Import Script from next/script and place this component inside the body of app/layout.tsx, after your existing children. Use your actual app ID in place of YOUR_APP_ID. The example uses macaron.sh; a self-hosted workspace should use its own deployed HTTPS origin.
Keep the script in one shared layout rather than adding it to every page. For chat in only one area, put it in that area’s layout. The afterInteractive strategy loads it after some hydration; it does not require turning your whole layout into a Client Component.
import Script from 'next/script';
// Inside <body>, after {children}:
<Script
id="macaron-support"
src="https://macaron.sh/macaron-support.js?v=notice-1"
data-app="YOUR_APP_ID"
strategy="afterInteractive"
/>3. Publish and verify the message round trip
A visible chat launcher proves that UI loaded, not that your team can reply. Use a clearly labeled test conversation and complete the customer-to-team-to-customer round trip on the deployed site.
- Open the website in a customer browser session and send a synthetic test message through the widget.
- Open that website’s inbox in Macaron and confirm the message belongs to the correct product.
- Reply from the inbox, return to the customer’s chat and confirm the reply is visible.
- Return to Set up chat and choose Check delivery. Confirm customer message received, team reply sent and reply loaded for the test conversation.
- Navigate to another page using your app’s normal links. Check that there is one chat launcher and that the conversation remains accessible.
- Refresh the page and repeat the check on a phone-sized screen, including opening, typing and closing chat with the keyboard.
If the widget or a reply is missing
Confirm chat is enabled for the same app ID used by the script. In browser developer tools, check that macaron-support.js loads and the request to /api/support/apps/YOUR_APP_ID/config succeeds. An incorrect app ID, disabled chat or an unreachable host is different from a message-delivery failure.
If your Content Security Policy blocks the integration, use the reported violation to allow the Macaron script, API connections, configured logo and widget styles. Follow your site’s existing nonce or policy approach; do not disable the policy to make the widget appear. Browser extensions can also block requests, so compare with a clean test session.
Use HTTPS for production. Keep the workspace’s authentication cookies, model keys and billing credentials out of the snippet. The public app ID identifies the product; it is not a model API key or a way to read the owner’s inbox.
Capture the browser context before starting a fix
When a conversation reveals a bug, ask for the route, browser, expected result and steps immediately before the failure. Record those facts in a report; chat does not automatically reproduce the problem or collect a full browser session replay.
Chat and reports work without a model key. A coding run is a separate action that needs repository access, a compatible machine and provider API access. Review the changes and checks, repeat the reproduction steps against the target release and add verification notes before marking the report resolved.