npm package: @hivegpt/hiveai-angular
Description: Angular library for the HiveGPT chatbot and voice agent.
Latest version: 0.0.613

# @hivegpt/hiveai-angular

Angular library for the HiveGPT chatbot and voice agent.

## Installation

```bash
npm install @hivegpt/hiveai-angular
```

Install peer dependencies if not already present:

```bash
npm install @angular/animations @angular/cdk @angular/common @angular/compiler @angular/core @angular/forms @angular/material @angular/platform-browser ngx-quill ngx-socket-io @pipecat-ai/client-js @pipecat-ai/websocket-transport
```

### Socket.IO v2 required (real-time chat)

If your backend uses **Socket.IO v2**, you must use a v2 client. If you see:

`Socket connection error: It seems you are trying to reach a Socket.IO server in v2.x with a v3.x client`

add this to **your application's** `package.json` (the app that uses this library), then run `npm install`:

```json
"overrides": {
  "socket.io-client": "2.5.0",
  "socket.io": "2.5.1"
}
```

If using Yarn, add instead:

```json
"resolutions": {
  "socket.io-client": "2.5.0",
  "socket.io": "2.5.1"
}
```

Then delete `node_modules` and the lockfile and reinstall.

## Usage

### 1. Import the module

In your Angular app module (e.g. `app.module.ts`):

```typescript
import { HiveGptModule } from '@hivegpt/hiveai-angular';

@NgModule({
  imports: [
    // ... other imports
    HiveGptModule,
  ],
})
export class AppModule { }
```

### 2. Use the chatbot component

In your template, add the chatbot and pass the required inputs:

```html
<hivegpt-chatbot
  [apiKey]="apiKey"
  [botId]="botId"
  [userId]="userId"
  [s27Token]="s27Token"
  [botName]="botName"
  [botSkills]="botSkills"
  [eventId]="eventId"
  [eventName]="eventName"
  [greeting]="greeting"
  [workspaceToken]="workspaceToken"
  [isDev]="isDev"
  [credentials]="credentials"
  [bgGradient]="bgGradient"
  [sendButtonColor]="sendButtonColor"
  [sendButtonTextColor]="sendButtonTextColor"
  [showClose]="showClose"
  [fullView]="fullView"
  [useOpenAi]="useOpenAi"
  [bgBubbleAi]="bgBubbleAi"
  [bgBubbleUser]="bgBubbleUser"
  [closeButtonbgColor]="closeButtonbgColor"
  [closeButtonColor]="closeButtonColor"
  [messageTextColorAi]="messageTextColorAi"
  [messageTextColorUser]="messageTextColorUser"
  [dateTimeColor]="dateTimeColor"
  [dateTextColor]="dateTextColor"
  [formFieldBgColor]="formFieldBgColor"
  [formFieldTextColor]="formFieldTextColor"
  [thumbsUpMessage]="thumbsUpMessage"
  [thumbsDownMessages]="thumbsDownMessages"
  [timezone]="timezone"
  [unknownResponses]="unknownResponses"
  [rules]="rules"
  [gradientColors]="gradientColors"
></hivegpt-chatbot>
```

### Inputs to pass (where the package is called)

| Input | Type | Required | Description |
|-------|------|----------|-------------|
| **apiKey** | string | Yes | API key for the bot. |
| **botId** | string | Yes | Bot identifier. |
| **userId** | string | Yes | User identifier. |
| **s27Token** | string | Yes | JWT for API auth; also used for **voice agent** (`POST /ai/ask-voice`). |
| **botName** | string | Yes | Display name for the bot. |
| **botSkills** | string | No | Bot skills / role description. |
| **eventId** | string | No | Event ID. |
| **eventName** | string | No | Event name. |
| **greeting** | string | No | Initial greeting message. |
| **workspaceToken** | string | No | Workspace token. |
| **credentials** | array | No | Credentials. |
| **bgGradient** | string[] | No | Background gradient colors. |
| **sendButtonColor** | string | No | Send button color. |
| **sendButtonTextColor** | string | No | Send button text color. |
| **showClose** | boolean | No | Show close button. |
| **fullView** | boolean | No | Use full-width drawer. |
| **useOpenAi** | boolean | No | Use OpenAI. |
| **bgBubbleAi** | string | No | AI bubble background. |
| **bgBubbleUser** | string | No | User bubble background. |
| **closeButtonbgColor** | string | No | Close button background. |
| **closeButtonColor** | string | No | Close button color. |
| **messageTextColorAi** | string | No | AI message text color. |
| **messageTextColorUser** | string | No | User message text color. |
| **dateTimeColor** | string | No | Date/time color. |
| **dateTextColor** | string | No | Date text color. |
| **formFieldBgColor** | string | No | Input field background. |
| **formFieldTextColor** | string | No | Input field text color. |
| **thumbsUpMessage** | string | No | Thumbs up message. |
| **thumbsDownMessages** | string[] | No | Thumbs down messages. |
| **timezone** | string | No | Timezone. |
| **unknownResponses** | array | No | Unknown response config. |
| **rules** | string | No | Rules. |
| **gradientColors** | string[] | No | Gradient colors. |
| **isDev** | boolean | No | If `true`, uses dev API base URL; otherwise prod. Pass through to chat-drawer so voice/chat use the correct backend. |

### Voice agent

The chatbot includes a **voice agent** (microphone button). For it to work you must pass:

- **s27Token** – JWT sent as `Authorization: Bearer <token>` to `POST baseurl/ai/ask-voice`.
- **botId** – Sent as `bot_id` in the request body.

The **base URL** for the API comes from the library’s environment (dev or prod, controlled by **isDev**). The library calls `POST {baseUrl}/ai/ask-voice` and uses the returned `ws_url` for the WebSocket. The chat drawer derives **conversation_id** from the current conversation and sends it with **bot_id** and **voice: "alloy"**. No extra input is needed for conversation context; ensure **apiKey**, **botId**, **userId**, **s27Token**, and **isDev** (if you need dev vs prod) are set where you use the package.

### Minimal example

```html
<hivegpt-chatbot
  [apiKey]="'your-api-key'"
  [botId]="'your-bot-id'"
  [userId]="'your-user-id'"
  [s27Token]="authToken"
  [botName]="'Assistant'"
  [eventId]="eventId"
  [eventName]="eventName"
  [greeting]="'Hello!'"
></hivegpt-chatbot>
```

Ensure your app provides a valid **s27Token** and, if needed, **isDev** so chat and voice agent use the correct API base URL.

## Code scaffolding

Run `ng generate component component-name --project eventsgpt-angular` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project eventsgpt-angular`.
> Note: Don't forget to add `--project eventsgpt-angular` or else it will be added to the default project in your `angular.json` file. 

## Build
Run `npx ng build @hivegpt/hiveai-angular` to build the project. The build artifacts will be stored in the `dist/` directory.

## Publishing

After building your library with `ng build eventsgpt-angular`, go to the dist folder `cd dist/eventsgpt-angular` and run `npm publish`.

## Running unit tests

Run `ng test eventsgpt-angular` to execute the unit tests via [Karma](https://karma-runner.github.io).

## Further help

To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.