npm package: @neurondata/emme-chat
Description: React chat component for Emme Agent.
Author: NeuronData
Latest version: 1.2.6


# @neurondata/emme-chat

**React chat component for Emme Agent.**

---

## 📦 Installation

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

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

---

## 🚀 Basic Usage

```tsx
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 <EmmeChat /> 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

```tsx
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](https://www.neurondata.com.br)