Medusa 2.0 chat widget plugin

Medusa 2.0 plugin to integrate Chat Widget for seller/buyer communication

Features

• Easy Integration
  • Simple script to copy-paste on your website, no coding required
  • No need to handle backend infrastructure — ConnectyCube takes care of it
• Superior feature set
  • Not just another basic chat widget - it's a complete chat system!
• Customizable UI
  • Modify colors, themes, and layout to match your brand’s design
• Real-time Messaging
  • Smooth, instant communication with no delays
• Moderation tools
  • Keep chats safe with message filtering, user bans, and admin controls
• Multimedia support
  • Send images, files, and emojis for richer conversations

Installation

Backend

1. Add plugin to your Medusa 2.0 core app:

   yarn add @connectycube/chat-widget-medusa-plugin
   

2. Create ConnectyCube account https://connectycube.com/signup and application, obtain credentials:

Also, go to Chat -> Custom Fields and create a new custom field called externalId:

3. Add the following variables to your .env file:

   VITE_BACKEND_URL=http://localhost:9000
   VITE_CHAT_APP_ID=<YOUR CONNECTYCUBE APP ID>
   VITE_CHAT_AUTH_KEY=<YOUR CONNECTYCUBE AUTH KEY>
   

   • VITE_BACKEND_URL - The URL of your Medusa backend, required for custom admin components.
   • VITE_CHAT_APP_ID - This is essential for authenticating your application with the ConnectyCube platform and accessing its chat services.
   • VITE_CHAT_AUTH_KEY - This key is used to authorize your application and ensure secure communication with the ConnectyCube SDK.

4. Add the following code to your medusa-config.ts file:

   1  module.exports = defineConfig({
   2    admin: {
   3      vite: (config) => {
   4          config.define["__VITE_CHAT_APP_ID__"] = JSON.stringify(process.env.VITE_CHAT_APP_ID);
   5          config.define["__VITE_CHAT_AUTH_KEY__"] = JSON.stringify(process.env.VITE_CHAT_AUTH_KEY);
   6          return {
   7              optimizeDeps: {
   8                  include: ["qs", "eventemitter3", "@xmpp/iq/callee", "@xmpp/resolve", "@xmpp/session-establishment", "@xmpp/client-core", "@xmpp/sasl-plain", "@xmpp/stream-features", "@xmpp/resource-binding", "@xmpp/reconnect", "@xmpp/middleware", "@xmpp/sasl-anonymous", "@xmpp/websocket", "@xmpp/iq/caller", "@xmpp/sasl"], // Will be merged with config that we use to run and build the dashboard.
   9              },
   10          };
   11      },
   12    },
   13    projectConfig: { ... },
   14    plugins: [
   15      {
   16        resolve: "@connectycube/chat-widget-medusa-plugin",
   17        options: {},
   18      },
   19    ],
   20  })

   This code connect plugin and helps to resolve an issue similar to https://github.com/medusajs/medusa/issues/11248.

5. Start the project:

   1yarn dev

Storefront

1. Add chat widget to your Storefront app:

   yarn add @connectycube/chat-widget
   

2. Add the following variables to your .env file:

   NEXT_PUBLIC_CHAT_APP_ID=<YOUR CONNECTYCUBE APP ID>
   NEXT_PUBLIC_CHAT_AUTH_KEY=<YOUR CONNECTYCUBE AUTH KEY>
   NEXT_PUBLIC_STORE_ID=<YOUR MEDUSA STORE ID>
   NEXT_PUBLIC_STORE_NAME=<YOUR MEDUSA STORE NAME>
   

3. Create src/ChatWidget.tsx component with the following content:

   1"use client"
   2
   3import React, { useEffect, useState } from "react"
   4import ConnectyCubeChatWidget from "@connectycube/chat-widget/react19"
   5import { StoreCustomer, StoreProduct } from "@medusajs/types"
   6 
   7export interface ChatWidgetProps {
   8  customer: StoreCustomer | null
   9  product: StoreProduct
   10  chatPerProduct?: boolean
   11}
   12 
   13export default function ChatWidget({
   14   customer,
   15   product,
   16   chatPerProduct,
   17}: ChatWidgetProps) {
   18
   19 const quickActions = {
   20    title: "Quick Actions",
   21    description:
   22      "Select an action from the options below or type a first message to start a conversation.",
   23    actions: [
   24      "Hi, I'm interested in this product.",
   25      "Can you tell me more about the price and payment options?",
   26      "Is the product still available?",
   27      "Can I schedule a viewing?",
   28    ],
   29  }
   30
   31 if (!customer) {
   32    return null
   33 }
   34
   35 const [defaultChat, setDefaultChat] = useState<any>(null)
   36 const [isOpen, setIsOpen] = useState<boolean>(false)
   37
   38 const onOpenCloseWidget = (isOpen: boolean) => {
   39   setIsOpen(isOpen)
   40 }
   41
   42 const storeId = process.env.NEXT_PUBLIC_STORE_ID
   43 const storeName = process.env.NEXT_PUBLIC_STORE_NAME
   44
   45 useEffect(() => {
   46   if (isOpen) {
   47     console.log("Widget is open:", isOpen)
   48     const defaultChatKey = chatPerProduct ? product.id : storeId
   49     const defaultChatName = chatPerProduct ? product.title : storeName
   50
   51     setDefaultChat({
   52       id: defaultChatKey,
   53       opponentUserId: storeId,
   54       type: "group",
   55       name: defaultChatName,
   56     })
   57   }
   58 }, [isOpen])
   59
   60 return (
   61   <div>
   62     <ConnectyCubeChatWidget
   63       // credentials
   64       appId={process.env.NEXT_PUBLIC_CHAT_APP_ID}
   65       authKey={process.env.NEXT_PUBLIC_CHAT_AUTH_KEY}
   66       userId={customer.id}
   67       userName={`${customer.first_name} ${customer.last_name}`}
   68       // settings
   69       showOnlineUsersTab={false}
   70       splitView={true}
   71       // quick actions
   72       quickActions={quickActions}
   73       // notifications
   74       showNotifications={true}
   75       playSound={true}
   76       // moderation
   77       enableContentReporting={true}
   78       enableBlockList={true}
   79       // last seen
   80       enableLastSeen={true}
   81       // url preview
   82       enableUrlPreview={true}
   83       limitUrlsPreviews={1}
   84       // attachments settings
   85       attachmentsAccept={"image/*,video/*,.pdf,audio/*"}
   86       // default chat
   87       defaultChat={defaultChat}
   88       onOpenChange={onOpenCloseWidget}
   89     />
   90   </div>
   91 )
   92}

4. update tsconfig.json:

   1{
   2  "compilerOptions": {
   3    "module": "nodenext",
   4    "moduleResolution": "nodenext",
   5    ...
   6  }
   7}

5. update storefront/src/app/[countryCode]/(main)/products/[handle]/page.tsx to retrieve customer info and pass it to ProductTemplate:

   1const customer = await retrieveCustomer()
   2return (
   3  <ProductTemplate
   4    product={pricedProduct}
   5    region={region}
   6    countryCode={params.countryCode}
   7    customer={customer}
   8  />
   9)

6. Finally, connect ChatWidget component on product details page, e.g. src/modules/products/templates/index.tsx

   1<ChatWidget
   2  customer={customer}
   3  product={product}
   4  chatPerProduct={true}
   5/>

Demo app

The complete demo app (backend + storefront) available https://github.com/ConnectyCube/chat-widget-medusa-plugin-demo-app

How can I use it?

On storefront, once logged in and opened product page, there will be a Chat toggle button bottom right:

Once clicked, a chat with seller will be opened where you can ask any product's related questions:

From Medusa dashboard there will be a new page called Chat, with the widget embedded, where all customers' chats are displayed, so you as a merchant can reply:

Have an issue?

Join our Discord for quick answers to your questions or file a GitHub issue

Community

• Blog
• X (twitter)@ConnectyCube
• Facebook

License

Apache 2.0