@neurondata/emme-chat

React chat component for Emme Agent.

📦 Installation

⚠️ Important: The recommended and stable version is 1.2.6.

npm install @neurondata/emme-chat
# or
yarn add @neurondata/emme-chat

🚀 Basic Usage

import { EmmeChat } from '@neurondata/emme-chat'

const App = () => {
  return (
    <EmmeChat
      config={{
        authentication: {
          baseUrl: 'https://api.yoursystem.com',
          internalPermissionToken: 'your-internal-token-here',
          token: 'optional-user-token'
        }
      }}
    />
  )
}
export default App;

⚠️ Note for Next.js: If you're using Next.js (App Router), the component that renders must include 'use client' at the top. This is because the chat component relies on browser-specific APIs and must run on the client side.

🔧 Props

EmmeChatProps

| Parameter | Type | Required | Description | | --------- | -------- | -------- | -------------------------------------------- | | config | Config | ✅ | Main configuration object for the chat | | theme | Theme | ❌ | Optional theme customization for the chat UI |

⚙️ Configuration (Config)

| Parameter | Type | Required | Description | | ------------------- | ------------------- | -------- | ---------------------------------------------------------------- | | authentication | Authentication | ✅ | API authentication configuration | | triggerButton | TriggerButton | ❌ | Optional settings for the chat trigger button | | chat | Chat | ❌ | Optional display mode and visibility settings | | agent | Agent | ❌ | Optional configuration for the chat agent | | userProfile | UserProfile | ❌ | Optional user profile settings | | exampleMessages | ExampleMessage[] | ❌ | Optional suggested messages shown before the conversation starts | | localization | Localization | ❌ | Optional localized messages and UI text | | supportedLanguage | SupportedLanguage | ❌ | Optional settings for chat language support |

🔐 Authentication

| Parameter | Type | Required | Description | | ------------------------- | --------------------- | -------- | ------------------------------------------------------------ | | baseUrl | string | ✅ | Base URL for the chat API | | internalPermissionToken | string | ✅ | Token for internal permission | | token | string | ❌ | Optional user token (JWT or similar) | | userNotFoundMessage | string | ❌ | Optional error message if user is not found | | customAuthentication | CustomAuthentication| ❌ | Optional custom authentication method |

🔑 CustomAuthentication

| Parameter | Type | Required | Description | | ----------------- | -------------------- | -------- | ------------------------------------------ | | method | 'GET' | ✅ | HTTP method used for authentication | | authType | 'BearerToken' | ✅ | Type of authentication | | token | string | ✅ | token for request | | apiUrl | string | ✅ | API endpoint for custom authentication | | responseType | 'json' | ✅ | Response format expected | | statusCodeSuccess | number | ✅ | Expected HTTP success code | | keyMappings | object | ✅ | Keys to map from response (username, language) |

💬 TriggerButton

| Parameter | Type | Required | Description | | ---------- | ------------ | -------- | ------------------------------------------ | | show | boolean | ❌ | Whether to display the trigger button | | text | LocalizationStructure[] | ❌ | Text shown on the button | | callback | () => void | ❌ | Optional function to be triggered on click |

🪟 Chat

| Parameter | Type | Required | Description | Options | | --------- | ------------------------- | -------- | ----------------------------- | ------------------------- | | isOpen | boolean | ❌ | If true, starts the chat open | true, false | | mode | 'fullscreen' \| 'popup' | ❌ | Chat display mode | 'fullscreen', 'popup' | | closeCallback | () => void | ❌ | A function to be executed when the chat is closed, allowing custom handling of the close event | | | footerContent | ReactNode | ❌ | Optional footer content for the chat | 2025 - v1.2.2 |

🤖 Agent

| Parameter | Type | Required | Description | | --------- | -------- | -------- | -------------------------------- | | name | string | ❌ | Agent's display name in the chat | | avatar | string | ❌ | Avatar image URL for the agent |

👤 UserProfile

| Parameter | Type | Required | Description | | --------- | -------- | -------- | -------------------------------- | | name | string | ❌ | User display name in the chat | | avatar | string | ❌ | Avatar image URL for the user |

💡 ExampleMessage

| Parameter | Type | Required | Description | | --------- | --------------------------- | -------- | ------------------------------------------------------------ | | id | string | ✅ | Unique identifier for the message (analytics, tracking, etc) | | text | LocalizationStructure[] | ✅ | Suggested message content in multiple languages |

🌍 Localization

| Parameter | Type | Required | Description | | ------------------------ | ------------------------- | -------- | ------------------------------------------ | | placeholderText | LocalizationStructure[] | ❌ | Input placeholder | | loadingMessage | LocalizationStructure[] | ❌ | Message while chat loads | | welcomeMessage | LocalizationStructure[] | ❌ | Initial message shown at startup | | fallbackMessage | LocalizationStructure[] | ❌ | Fallback message if no answer is available | | loginWelcomeMessage | LocalizationStructure[] | ❌ | Message shown on the login screen | | loginErrorMessage | LocalizationStructure[] | ❌ | Error message for failed login | | loginSendMessageText | LocalizationStructure[] | ❌ | Text on send button in login form | | loginInputUsernameText | LocalizationStructure[] | ❌ | Placeholder for username input | | loginInputPasswordText | LocalizationStructure[] | ❌ | Placeholder for password input |

⚠️ Important: The welcomeMessage text supports dynamic placeholders: {username} and {language}.
For example: "Hello {username}!\nYour selected language is {language}."
These placeholders will be automatically replaced with the corresponding user data at runtime.

🌐 SupportedLanguage

| Parameter | Type | Required | Description | Options | | ------------------ | ------------------- | -------- | ---------------------------- | ---------------------------------------------------------------- | | defaultLanguage | LanguageOptions | ❌ | Default language of the chat | 'pt-BR', 'pt-PT', 'en-US', 'en-GB', 'es-ES', 'zh-CN', 'ja-JP' | | allowedLanguages | LanguageOptions[] | ❌ | List of supported languages | Same as above |

🗨️ LocalizationStructure

| Parameter | Type | Description | | --------- | ----------------- | ------------------------- | | key | LanguageOptions | Language identifier | | text | string | Localized text content |

🎨 Theme

| Parameter | Type | Description | | ------------------------ | -------- | ---------------------------------------------------------------- | | fontFamily | string | Font family for the chat UI | | lineHeight | number | Base line height for text | | colorPrimary | string | Main action color (buttons, highlights) | | colorBackground | string | Background color of the chat UI | | colorBorder | string | Color used for borders | | colorIconExpand | string | Color of the expand icon | | colorIconClosed | string | Color of the close icon | | colorIconGather | string | Color of the gather icon (used to shrink the chat) | | colorIconRefresh | string | Color of the refresh icon | | colorIconSend | string | Color of the send icon | | colorIconAlert | string | Color of the alert icon | | colorIconUserAlert | string | Color of the user icon in alert | | colorTextUserAlert | string | Text color of messages user alert | | colorIconMessageCircle | string | Color of the message circle icon | | colorNameAgent | string | Text color for the agent's name | | colorTextMsgAgent | string | Text color for agent messages | | colorBackgroundMsgAgent| string | Background color for agent messages | | colorTextMsgUser | string | Text color for user messages | | colorPlaceholder | string | Color of input placeholder text | | colorTextInput | string | Color of input text | | colorTextButton | string | Color of text on buttons | | colorLoaderDots | string | Color of loading animation dots |

📌 Full Example

import { EmmeChat } from '@neurondata/emme-chat'

const App = () => {

  return 
  <EmmeChat config={{
    authentication: {
      baseUrl: 'https://api.yoursystem.com',
      internalPermissionToken: 'abc123',
      token: 'optional-jwt',
      customAuthentication: {
        method: 'GET',
        apiUrl: 'https://api.external.com/auth',
        authType: 'BearerToken',
        token:'my-token',
        statusCodeSuccess: 200,
        responseType: 'json',
        keyMappings: {
          username: 'name',
        }
      }
    },
    triggerButton: {
      show: true,
      text: [
        { key: 'en-US', text: 'Chat with us' },
        { key: 'pt-BR', text: 'Fale conosco' },
      ],
      callback: () => console.log('Chat opened'),
    },
    chat: {
      isOpen: false,
      mode: 'popup',
      footerContent: '2025 - v1.2.2',
    },
    agent: {
      name: 'Emme',
      avatar: 'https://link-to-avatar.com/avatar.png',
    },
    userProfile: {
      name: 'User Teste',
      avatar: 'https://link-to-avatar.com/avatar-user.png',
    },
    exampleMessages: [
      {
        id: '1',
        text: [
          { key: 'en-US', text: 'I need help with an order' },
          { key: 'pt-BR', text: 'Preciso de ajuda com um pedido' },
        ],
      },
      {
        id: '2',
        text: [
          { key: 'en-US', text: 'I want to speak with an agent' },
          { key: 'pt-BR', text: 'Quero falar com um agente' },
        ],
      },
    ],
    localization: {
      welcomeMessage: [
        { key: 'en-US', text: 'Hello! How can I help you?' },
        { key: 'pt-BR', text: 'Olá! Como posso te ajudar?' }, 
      ],
      placeholderText: [
        { key: 'en-US', text: 'Type your message...' },
        { key: 'pt-BR', text: 'Digite sua mensagem...' }, 
      ],
      fallbackMessage: [
        { key: 'en-US', text: 'Sorry, I didn’t understand your question.' },
        { key: 'pt-BR', text: 'Desculpe, não entendi sua pergunta.' }, 
      ],
      loginWelcomeMessage: [
        { key: 'en-US', text: 'Welcome, please log in to continue.' },
        { key: 'pt-BR', text: 'Bem-vindo, por favor faça login para continuar.' }, 
      ],
      loginErrorMessage: [
        { key: 'en-US', text: 'Invalid username or password.' },
        { key: 'pt-BR', text: 'Usuário ou senha inválidos.' }, 
      ],
      loginButtonText: [
        { key: 'en-US', text: 'Log in' },
        { key: 'pt-BR', text: 'Entrar' }, 
      ],
      loginInputUsernamePlaceholder: [
        { key: 'en-US', text: 'Username' },
        { key: 'pt-BR', text: 'Usuário' }, 
      ],
      loginInputPasswordPlaceholder: [
        { key: 'en-US', text: 'Password' },
        { key: 'pt-BR', text: 'Senha' }, 
      ],
    },
    supportedLanguage: {
      defaultLanguage: 'pt-BR',
      allowedLanguages: ['pt-BR', 'en-US'],
    },
  }}
    theme={{
      fontFamily: "'Roboto', sans-serif",
      lineHeight: 1.7,
      colorPrimary: "#FF5733",
      colorBackground: "#F5F5F5",
      colorBorder: "#D1D5DB",
      colorIconExpand: "#4B5563",
      colorIconClosed: "#6B7280",
      colorIconGather: "#9CA3AF",
      colorIconRefresh: "#3B82F6",
      colorIconSend: "#10B981",
      colorIconAlert:'#FF5733',
      colorIconUserAlert:'#3360F6',
      colorTextUserAlert:'#FF5733',
      colorIconMessageCircle: "#E5E7EB",
      colorNameAgent: "#1F2937",
      colorTextMsgAgent: "#374151",
      colorBackgroundMsgAgent: "#E0E7FF",
      colorTextMsgUser: "#F9FAFB",
      colorPlaceholder: "#A1A1AA",
      colorTextInput: "#111827",
      colorTextButton: "#FFFFFF",
      colorLoaderDots: "#8B5CF6",
    }}
  />
}

export default App

🧾 License

MIT © NeuronData